diff --git a/.gitignore b/.gitignore index 52a771d45413d3ec03f4bc9122dc81e4068222dd..b538d1bf1512c5cad62ab49c09b310c7a16ef618 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ # FOLDERS node_modules -public saved_files official editing @@ -13,7 +12,6 @@ temp.docx API.css API.html html_to_docx_output.docx -~$* editing.zip package.json package-lock.json diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index db9d5d3c39971190451cd4d1f76182e375904af6..d5983c3138ee0ec0609a5ee36211b6e398cbc055 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,33 +1,9 @@ stages: - - preprocessing - - chunk - - build - deploy variables: DOCKER_DRIVER: overlay2 -git: - stage: deploy - variables: - GIT_USER: "HTML_SPEC_TOKEN" - GIT_EMAIL: "project_47_bot_07ebaee9ab01682982f3e84d2c5d59d7@gitlab.example.com" - script: #copy into public everything it needs to make the page work - - cp ./API/*.html public/editing/ #editing_html files - # - cp -r ./API/dist/ public/editing/ #javascript files - - cp -r ./API/media/ public/editing/ #images - - cp styles.css styling.css public/ #css files - - unzip official.zip -d public/official/ - after_script: - - docker run --rm -u $(id -u):$(id -g) --entrypoint "/bin/sh" -v "./:/data" bitnami/git -c "cd data && git remote set-url gitlab_origin https://HTML_SPEC_TOKEN:$HTML_SPEC_TOKEN@forge.etsi.org/rep/cim/NGSI-LD.git && git add public/official/ && git add public/index.html && git add public/*.css && git commit -m 'output from pipeline' && git push gitlab_origin HEAD:html_specification -o ci.skip" - rules: - - changes: - - API.docx - - if: $CI_PIPELINE_SOURCE == "manual" - artifacts: - paths: - - public - pages: stage: deploy needs: diff --git a/API-html/0--1.html b/API-html/0--1.html deleted file mode 100644 index 396dc0ee20f4bdf1ddfc84ab1cc058a76d2cc85b..0000000000000000000000000000000000000000 --- a/API-html/0--1.html +++ /dev/null @@ -1,2411 +0,0 @@ - - - - - - - -consolidated - - - - - - - - -
-

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

-
-
-

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.

-
-

Group Specification

-
-

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 availablein theMilestones listing.

-

If you find errors in the present document, please send your comments tothe relevant service listed underCommittee 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.

-
-

Contents

-
-

Intellectual Property Rights 20

-

Foreword 20

-

Modal verbs terminology 20

-

Executive summary 20

-

Introduction 21

-

1 Scope 22

-

2 References 22

-

2.1 Normative references 22

-

2.2 Informative references 23

-

3 Definition of terms, symbols and abbreviations 24

-

3.1 Terms 24

-

3.2 Symbols 27

-

3.3 Abbreviations 27

-

4 Context Information Management Framework 29

-

4.1 Introduction 29

-

4.2 NGSI-LD Information Model 29

-

4.2.1 Introduction 29

-

4.2.2 NGSI-LD Meta Model 30

-

4.2.3 Cross Domain Ontology 31

-

4.2.4 NGSI-LD domain-specific models and instantiation 32

-

4.2.5 UML representation 32

-

4.3 NGSI-LD Architectural Considerations 33

-

4.3.1 Introduction 33

-

4.3.2 Centralized architecture 33

-

4.3.3 Distributed architecture 34

-

4.3.4 Federated architecture 35

-

4.3.5 NGSI-LD API Structure and Implementation Options 36

-

4.3.6 Distributed Operations 41

-

4.3.6.1 Introduction 41

-

4.3.6.2 Additive Registrations 42

-

4.3.6.3 Proxied Registrations 42

-

4.3.6.4 Limiting Cascading Distributed Operations 43

-

4.3.6.5 Extra information to provide when contacting Context Source 43

-

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

-

4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations 44

-

4.3.6.8 Backwards compatibility of Context Source payloads 45

-

4.3.7 Snapshots 46

-

4.4 Core and user NGSI-LD @context 47

-

4.5 NGSI-LD Data Representation 48

-

4.5.0 Introduction 48

-

4.5.1 NGSI-LD Entity Representation 48

-

4.5.2 NGSI-LD Property Representations 49

-

4.5.2.1 Introduction 49

-

4.5.2.2 Normalized NGSI-LD Property 49

-

4.5.2.3 Concise NGSI-LD Property 50

-

4.5.3 NGSI-LD Relationship Representations 52

-

4.5.3.1 Introduction 52

-

4.5.3.2 Normalized NGSI-LD Relationship 52

-

4.5.3.3 Concise NGSI-LD Relationship 53

-

4.5.4 Simplified Representation 55

-

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 66

-

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 69

-

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 71

-

4.5.20 NGSI-LD VocabProperty Representations 73

-

4.5.20.1 Introduction 73

-

4.5.20.2 Normalized NGSI-LD VocabProperty 73

-

4.5.20.3 Concise NGSI-LD VocabProperty 74

-

4.5.21 NGSI-LD ListProperty Representations 74

-

4.5.21.1 Introduction 74

-

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 76

-

4.5.23 NGSI-LD Linked Entity Retrieval 77

-

4.5.23.1 Introduction 77

-

4.5.23.2 Inline Linked Entity Representation 77

-

4.5.23.3 Flattened Linked Entity Representation 77

-

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 78

-

4.5.25 NGSI-LD EntityMap Representation 79

-

4.6 Data Representation Restrictions 79

-

4.6.1 Supported text encodings 79

-

4.6.2 Supported names 79

-

4.6.3 Supported data types for Values 80

-

4.6.4 Supported Content 81

-

4.6.5 Supported data types for LanguageMaps 81

-

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

-

4.7 Geospatial Properties 82

-

4.7.1 GeoJSON Geometries 82

-

4.7.2 Representation of GeoJSON Geometries in JSON-LD 82

-

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 91

-

4.11 NGSI-LD Temporal Query Language 93

-

4.12 NGSI-LD Pagination 94

-

4.13 Counting the Number of Results 95

-

4.14 Supporting Multiple Tenants 95

-

4.15 NGSI-LD Language Filter 95

-

4.16 Supporting Multiple Entity Types 96

-

4.17 NGSI-LD Entity Type Selection Language 96

-

4.18 NGSI-LD Scopes 97

-

4.19 NGSI-LD Scope Query Language 97

-

4.20 NGSI-LD Distributed Operation names 98

-

4.21 NGSI-LD Attribute Projection Language 100

-

4.22 Transient Storage of Entities and Attributes 100

-

4.23 Entity Ordering 101

-

4.23.1 Introduction 101

-

4.23.2 Datatype Comparison Order 101

-

4.23.3 NGSI-LD Entity Ordering Language 102

-

5 API Operation Definition 103

-

5.1 Introduction 103

-

5.2 Data Types 103

-

5.2.1 Introduction 103

-

5.2.2 Common members 103

-

5.2.3 @context 104

-

5.2.4 Entity 104

-

5.2.5 Property 105

-

5.2.6 Relationship 107

-

5.2.7 GeoProperty 109

-

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 122

-

5.2.17 BatchEntityError 122

-

5.2.18 UpdateResult 123

-

5.2.19 NotUpdatedDetails 123

-

5.2.20 EntityTemporal 123

-

5.2.21 TemporalQuery 123

-

5.2.22 KeyValuePair 124

-

5.2.23 Query 125

-

5.2.24 EntityTypeList 127

-

5.2.25 EntityType 127

-

5.2.26 EntityTypeInfo 127

-

5.2.27 AttributeList 128

-

5.2.28 Attribute 128

-

5.2.29 Feature 129

-

5.2.30 FeatureCollection 129

-

5.2.31 FeatureProperties 130

-

5.2.32 LanguageProperty 130

-

5.2.33 EntitySelector 132

-

5.2.34 RegistrationManagementInfo 133

-

5.2.35 VocabProperty 133

-

5.2.36 ListProperty 135

-

5.2.37 ListRelationship 137

-

5.2.38 JsonProperty 139

-

5.2.39 EntityMap 141

-

5.2.40 Context Source Identity 142

-

5.2.41 Snapshot 142

-

5.2.42 ExecutionResultDetails 144

-

5.2.43 OrderingParams 145

-

5.2.44 AggregationParams 145

-

5.3 Notification data types 146

-

5.3.1 Notification 146

-

5.3.2 CSourceNotification 146

-

5.3.3 TriggerReasonEnumeration 147

-

5.3.4 SnapshotNotification 147

-

5.4 NGSI-LD Fragments 148

-

5.5 Common Behaviours 149

-

5.5.1 Introduction 149

-

5.5.2 Error types 149

-

5.5.3 Error response payload body 150

-

5.5.4 General NGSI-LD validation 150

-

5.5.5 Default @context assignment 151

-

5.5.6 Operation execution and generic error handling 151

-

5.5.7 Term to URI expansion or compaction 151

-

5.5.8 Partial Update Patch Behaviour 152

-

5.5.9 Pagination Behaviour 154

-

5.5.9.1 General Pagination Behaviour 154

-

5.5.9.2 Pagination option using limit and offset 155

-

5.5.9.3 Pagination with Entity maps 155

-

5.5.10 Multi-Tenant Behaviour 155

-

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

-

5.5.11.0 Foreword 156

-

5.5.11.1 Batch Entity Creation case 156

-

5.5.11.2 Batch Entity Creation or Update (Upsert) case 156

-

5.5.11.3 Batch Entity Update case 156

-

5.5.11.4 Batch Entity Delete case 156

-

5.5.11.5 Batch Entity Merge case 157

-

5.5.12 Merge Patch Behaviour 157

-

5.5.13 Limiting operations to local scope 158

-

5.5.14 Distributed Transactional Behaviour 159

-

5.5.15 Snapshot Behaviour 159

-

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 160

-

5.6.1.3 Input data 160

-

5.6.1.4 Behaviour 160

-

5.6.1.5 Output data 161

-

5.6.2 Update Attributes 161

-

5.6.2.1 Description 161

-

5.6.2.2 Use case diagram 161

-

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 163

-

5.6.3.1 Description 163

-

5.6.3.2 Use case diagram 163

-

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 165

-

5.6.4.3 Input data 165

-

5.6.4.4 Behaviour 165

-

5.6.4.5 Output data 166

-

5.6.5 Delete Attribute 166

-

5.6.5.1 Description 166

-

5.6.5.2 Use case diagram 166

-

5.6.5.3 Input data 167

-

5.6.5.4 Behaviour 167

-

5.6.5.5 Output data 167

-

5.6.6 Delete Entity 168

-

5.6.6.1 Description 168

-

5.6.6.2 Use case diagram 168

-

5.6.6.3 Input data 168

-

5.6.6.4 Behaviour 168

-

5.6.6.5 Output data 169

-

5.6.7 Batch Entity Creation 169

-

5.6.7.1 Description 169

-

5.6.7.2 Use case diagram 169

-

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 173

-

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 175

-

5.6.10.5 Output data 176

-

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

-

5.6.11.1 Description 176

-

5.6.11.2 Use case diagram 176

-

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 178

-

5.6.12.4 Behaviour 178

-

5.6.12.5 Output data 179

-

5.6.13 Delete Attribute from Temporal Evolution of an Entity 179

-

5.6.13.1 Description 179

-

5.6.13.2 Use case diagram 179

-

5.6.13.3 Input data 180

-

5.6.13.4 Behaviour 180

-

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 181

-

5.6.14.3 Input data 181

-

5.6.14.4 Behaviour 182

-

5.6.14.5 Output data 182

-

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity 182

-

5.6.15.1 Description 182

-

5.6.15.2 Use case diagram 183

-

5.6.15.3 Input data 183

-

5.6.15.4 Behaviour 183

-

5.6.15.5 Output data 184

-

5.6.16 Delete Temporal Evolution of an Entity 184

-

5.6.16.1 Description 184

-

5.6.16.2 Use case diagram 184

-

5.6.16.3 Input data 184

-

5.6.16.4 Behaviour 185

-

5.6.16.5 Output data 185

-

5.6.17 Merge Entity 185

-

5.6.17.1 Description 185

-

5.6.17.2 Use case diagram 185

-

5.6.17.3 Input data 186

-

5.6.17.4 Behaviour 186

-

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 188

-

5.6.18.4 Behaviour 188

-

5.6.18.5 Output data 189

-

5.6.19 Replace Attribute 189

-

5.6.19.1 Description 189

-

5.6.19.2 Use case diagram 189

-

5.6.19.3 Input data 190

-

5.6.19.4 Behaviour 190

-

5.6.19.5 Output data 190

-

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 191

-

5.6.20.4 Behaviour 191

-

5.6.20.5 Output data 192

-

5.6.21 Purge Entities 192

-

5.6.21.1 Description 192

-

5.6.21.2 Use case diagram 192

-

5.6.21.3 Input data 193

-

5.6.21.4 Behaviour 193

-

5.6.21.5 Output data 194

-

5.7 Context Information Consumption 195

-

5.7.1 Retrieve Entity 195

-

5.7.1.1 Description 195

-

5.7.1.2 Use case diagram 195

-

5.7.1.3 Input data 195

-

5.7.1.4 Behaviour 196

-

5.7.1.5 Output data 197

-

5.7.2 Query Entities 198

-

5.7.2.1 Description 198

-

5.7.2.2 Use case diagram 198

-

5.7.2.3 Input data 198

-

5.7.2.4 Behaviour 200

-

5.7.2.5 Output data 202

-

5.7.3 Retrieve Temporal Evolution of an Entity 203

-

5.7.3.1 Description 203

-

5.7.3.2 Use case diagram 203

-

5.7.3.3 Input data 203

-

5.7.3.4 Behaviour 204

-

5.7.3.5 Output data 205

-

5.7.4 Query Temporal Evolution of Entities 205

-

5.7.4.1 Description 205

-

5.7.4.2 Use case diagram 205

-

5.7.4.3 Input data 206

-

5.7.4.4 Behaviour 207

-

5.7.4.5 Output Data 210

-

5.7.5 Retrieve Available Entity Types 210

-

5.7.5.1 Description 210

-

5.7.5.2 Use case diagram 210

-

5.7.5.3 Input data 211

-

5.7.5.4 Behaviour 211

-

5.7.5.5 Output data 211

-

5.7.6 Retrieve Details of Available Entity Types 211

-

5.7.6.1 Description 211

-

5.7.6.2 Use case diagram 211

-

5.7.6.3 Input data 211

-

5.7.6.4 Behaviour 211

-

5.7.6.5 Output data 212

-

5.7.7 Retrieve Available Entity Type Information 212

-

5.7.7.1 Description 212

-

5.7.7.2 Use case diagram 212

-

5.7.7.3 Input data 212

-

5.7.7.4 Behaviour 212

-

5.7.7.5 Output data 212

-

5.7.8 Retrieve Available Attributes 213

-

5.7.8.1 Description 213

-

5.7.8.2 Use case diagram 213

-

5.7.8.3 Input data 213

-

5.7.8.4 Behaviour 213

-

5.7.8.5 Output data 213

-

5.7.9 Retrieve Details of Available Attributes 213

-

5.7.9.1 Description 213

-

5.7.9.2 Use case diagram 214

-

5.7.9.3 Input data 214

-

5.7.9.4 Behaviour 214

-

5.7.9.5 Output data 214

-

5.7.10 Retrieve Available Attribute Information 214

-

5.7.10.1 Description 214

-

5.7.10.2 Use case diagram 214

-

5.7.10.3 Input data 215

-

5.7.10.4 Behaviour 215

-

5.7.10.5 Output data 215

-

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

-

5.8 Context Information Subscription 216

-

5.8.1 Create Subscription 216

-

5.8.1.1 Description 216

-

5.8.1.2 Use case diagram 216

-

5.8.1.3 Input data 216

-

5.8.1.4 Behaviour 216

-

5.8.1.5 Output data 218

-

5.8.2 Update Subscription 218

-

5.8.2.1 Description 218

-

5.8.2.2 Use case diagram 218

-

5.8.2.3 Input data 218

-

5.8.2.4 Behaviour 219

-

5.8.2.5 Output data 219

-

5.8.3 Retrieve Subscription 219

-

5.8.3.1 Description 219

-

5.8.3.2 Use case diagram 219

-

5.8.3.3 Input data 220

-

5.8.3.4 Behaviour 220

-

5.8.3.5 Output data 220

-

5.8.4 Query Subscriptions 220

-

5.8.4.1 Description 220

-

5.8.4.2 Use case diagram 220

-

5.8.4.3 Input data 221

-

5.8.4.4 Behaviour 221

-

5.8.4.5 Output data 221

-

5.8.5 Delete Subscription 221

-

5.8.5.1 Description 221

-

5.8.5.2 Use case diagram 221

-

5.8.5.3 Input data 222

-

5.8.5.4 Behaviour 222

-

5.8.5.5 Output data 222

-

5.8.6 Notification behaviour 222

-

5.9 Context Source Registration 224

-

5.9.1 Introduction 224

-

5.9.2 Register Context Source 224

-

5.9.2.1 Description 224

-

5.9.2.2 Use case diagram 225

-

5.9.2.3 Input data 225

-

5.9.2.4 Behaviour 225

-

5.9.2.5 Output data 226

-

5.9.3 Update Context Source Registration 226

-

5.9.3.1 Description 226

-

5.9.3.2 Use case diagram 226

-

5.9.3.3 Input data 226

-

5.9.3.4 Behaviour 227

-

5.9.3.5 Output data 227

-

5.9.4 Delete Context Source Registration 227

-

5.9.4.1 Description 227

-

5.9.4.2 Use case diagram 227

-

5.9.4.3 Input data 228

-

5.9.4.4 Behaviour 228

-

5.9.4.5 Output data 228

-

5.10 Context Source Discovery 228

-

5.10.1 Retrieve Context Source Registration 228

-

5.10.1.1 Description 228

-

5.10.1.2 Use case diagram 228

-

5.10.1.3 Input data 229

-

5.10.1.4 Behaviour 229

-

5.10.1.5 Output data 229

-

5.10.2 Query Context Source Registrations 229

-

5.10.2.1 Description 229

-

5.10.2.2 Use case diagram 230

-

5.10.2.3 Input data 230

-

5.10.2.4 Behaviour 231

-

5.10.2.5 Output data 232

-

5.11 Context Source Registration Subscription 232

-

5.11.1 Introduction 232

-

5.11.2 Create Context Source Registration Subscription 232

-

5.11.2.1 Description 232

-

5.11.2.2 Use case diagram 232

-

5.11.2.3 Input data 232

-

5.11.2.4 Behaviour 233

-

5.11.2.5 Output data 233

-

5.11.3 Update Context Source Registration Subscription 234

-

5.11.3.1 Description 234

-

5.11.3.2 Use case diagram 234

-

5.11.3.3 Input data 234

-

5.11.3.4 Behaviour 234

-

5.11.3.5 Output data 234

-

5.11.4 Retrieve Context Source Registration Subscription 234

-

5.11.4.1 Description 234

-

5.11.4.2 Use case diagram 235

-

5.11.4.3 Input data 235

-

5.11.4.4 Behaviour 235

-

5.11.4.5 Output data 235

-

5.11.5 Query Context Source Registration Subscriptions 235

-

5.11.5.1 Description 235

-

5.11.5.2 Use case diagram 235

-

5.11.5.3 Input data 236

-

5.11.5.4 Behaviour 236

-

5.11.5.5 Output data 236

-

5.11.6 Delete Context Source Registration Subscription 236

-

5.11.6.1 Description 236

-

5.11.6.2 Use case diagram 236

-

5.11.6.3 Input data 237

-

5.11.6.4 Behaviour 237

-

5.11.6.5 Output data 237

-

5.11.7 Notification behaviour 237

-

5.12 Matching Context Source Registrations 238

-

5.13 Storing, Managing and Serving @contexts 239

-

5.13.1 Introduction 239

-

5.13.2 Add @context 240

-

5.13.2.1 Description 240

-

5.13.2.2 Use case diagram 240

-

5.13.2.3 Input data 240

-

5.13.2.4 Behaviour 241

-

5.13.2.5 Output data 241

-

5.13.3 List @contexts 241

-

5.13.3.1 Description 241

-

5.13.3.2 Use case diagram 241

-

5.13.3.3 Input data 241

-

5.13.3.4 Behaviour 242

-

5.13.3.5 Output data 242

-

5.13.4 Serve @context 242

-

5.13.4.1 Description 242

-

5.13.4.2 Use case diagram 242

-

5.13.4.3 Input data 243

-

5.13.4.4 Behaviour 243

-

5.13.4.5 Output data 243

-

5.13.5 Delete and Reload @context 243

-

5.13.5.1 Description 243

-

5.13.5.2 Use case diagram 243

-

5.13.5.3 Input data 244

-

5.13.5.4 Behaviour 244

-

5.13.5.5 Output data 244

-

5.14 Context Source Entity Mapping 244

-

5.14.1 Retrieve EntityMap 244

-

5.14.1.1 Description 244

-

5.14.1.2 Use case diagram 244

-

5.14.1.3 Input data 245

-

5.14.1.4 Behaviour 245

-

5.14.1.5 Output data 245

-

5.14.2 Update EntityMap 245

-

5.14.2.1 Description 245

-

5.14.2.2 Use case diagram 245

-

5.14.2.3 Input data 246

-

5.14.2.4 Behaviour 246

-

5.14.2.5 Output data 246

-

5.14.3 Delete EntityMap 246

-

5.14.3.1 Description 246

-

5.14.3.2 Use case diagram 246

-

5.14.3.3 Input data 247

-

5.14.3.4 Behaviour 247

-

5.14.3.5 Output data 247

-

5.14.4 Create EntityMap for Query Entities 247

-

5.14.4.1 Description 247

-

5.14.4.2 Use case diagram 247

-

5.14.4.3 Input data 248

-

5.14.4.4 Behaviour 249

-

5.14.4.5 Output data 250

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities 251

-

5.14.5.1 Description 251

-

5.14.5.2 Use case diagram 251

-

5.14.5.3 Input data 251

-

5.14.5.4 Behaviour 252

-

5.14.5.5 Output Data 254

-

5.15 Context Source Identity Information 254

-

5.15.1 Retrieve Context Source Identity Information 254

-

5.15.1.1 Description 254

-

5.15.1.2 Use case diagram 254

-

5.15.1.3 Input data 255

-

5.15.1.4 Behaviour 255

-

5.15.1.5 Output data 255

-

5.16 Snapshot Functionality 255

-

5.16.1 Create Snapshot 255

-

5.16.1.1 Description 255

-

5.16.1.2 Use case diagram 255

-

5.16.1.3 Input data 255

-

5.16.1.4 Behaviour 256

-

5.16.1.5 Output data 256

-

5.16.2 Clone Snapshot 256

-

5.16.2.1 Description 256

-

5.16.2.2 Use case diagram 256

-

5.16.2.3 Input data 257

-

5.16.2.4 Behaviour 257

-

5.16.2.5 Output data 258

-

5.16.3 Retrieve Snapshot Status 258

-

5.16.3.1 Description 258

-

5.16.3.2 Use case diagram 258

-

5.16.3.3 Input data 258

-

5.16.3.4 Behaviour 258

-

5.16.3.5 Output data 258

-

5.16.4 Update Snapshot Status 258

-

5.16.4.1 Description 258

-

5.16.4.2 Use case diagram 259

-

5.16.4.3 Input data 259

-

5.16.4.4 Behaviour 259

-

5.16.4.5 Output data 259

-

5.16.5 Delete Snapshot 259

-

5.16.5.1 Description 259

-

5.16.5.2 Use case diagram 260

-

5.16.5.3 Input data 260

-

5.16.5.4 Behaviour 260

-

5.16.5.5 Output data 260

-

5.16.6 Snapshot status notification behaviour 260

-

5.16.7 Purge Snapshots 261

-

5.16.7.1 Description 261

-

5.16.7.2 Use case diagram 261

-

5.16.7.3 Input data 261

-

5.16.7.4 Behaviour 261

-

5.16.7.5 Output data 261

-

6 API HTTP Binding 261

-

6.1 Introduction 261

-

6.2 Global Definitions and Resource Structure 262

-

6.3 Common Behaviours 267

-

6.3.1 Introduction 267

-

6.3.2 Error Types 267

-

6.3.3 Reporting errors 267

-

6.3.4 HTTP request preconditions 267

-

6.3.5 JSON-LD @context resolution 268

-

6.3.6 HTTP response common requirements 269

-

6.3.7 Representation of Entities 269

-

6.3.8 Notification behaviour 270

-

6.3.9 Csource Notification behaviour 271

-

6.3.10 Pagination behaviour 271

-

6.3.11 Including system Attributes 273

-

6.3.12 Simplified or aggregated temporal representation of Entities 273

-

6.3.13 Counting number of results 274

-

6.3.14 Tenant specification 274

-

6.3.15 GeoJSON representation of spatially bound entities 275

-

6.3.16 Expiration time for cached @contexts 275

-

6.3.17 Distributed Operations Caching and Timeout Behaviour 275

-

6.3.18 Limiting Distributed Operations 276

-

6.3.19 Extra information to provide when contacting Context Source 276

-

6.3.20 Invalid parameters 277

-

6.3.21 Optional profile information regarding versioning and datatype conformance 277

-

6.3.22 Snapshot specification 277

-

6.4 Resource: entities/ 277

-

6.4.1 Description 277

-

6.4.2 Resource definition 277

-

6.4.3 Resource methods 277

-

6.4.3.1 POST 277

-

6.4.3.2 GET 279

-

6.4.3.3 DELETE 283

-

6.5 Resource: entities/{entityId} 285

-

6.5.1 Description 285

-

6.5.2 Resource definition 286

-

6.5.3 Resource methods 286

-

6.5.3.1 GET 286

-

6.5.3.2 DELETE 288

-

6.5.3.3 PUT 289

-

6.5.3.4 PATCH 291

-

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

-

6.6.1 Description 292

-

6.6.2 Resource definition 292

-

6.6.3 Resource methods 293

-

6.6.3.1 POST 293

-

6.6.3.2 PATCH 294

-

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

-

6.7.1 Description 295

-

6.7.2 Resource definition 295

-

6.7.3 Resource methods 296

-

6.7.3.1 PATCH 296

-

6.7.3.2 DELETE 297

-

6.7.3.3 PUT 298

-

6.8 Resource: csourceRegistrations/ 300

-

6.8.1 Description 300

-

6.8.2 Resource definition 300

-

6.8.3 Resource methods 300

-

6.8.3.1 POST 300

-

6.8.3.2 GET 301

-

6.9 Resource: csourceRegistrations/{registrationId} 303

-

6.9.1 Description 303

-

6.9.2 Resource definition 303

-

6.9.3 Resource methods 304

-

6.9.3.1 GET 304

-

6.9.3.2 PATCH 304

-

6.9.3.3 DELETE 305

-

6.10 Resource: subscriptions/ 306

-

6.10.1 Description 306

-

6.10.2 Resource definition 306

-

6.10.3 Resource methods 306

-

6.10.3.1 POST 306

-

6.10.3.2 GET 307

-

6.11 Resource: subscriptions/{subscriptionId} 308

-

6.11.1 Description 308

-

6.11.2 Resource definition 308

-

6.11.3 Resource methods 308

-

6.11.3.1 GET 308

-

6.11.3.2 PATCH 309

-

6.11.3.3 DELETE 309

-

6.12 Resource: csourceSubscriptions/ 310

-

6.12.1 Description 310

-

6.12.2 Resource definition 310

-

6.12.3 Resource methods 310

-

6.12.3.1 POST 310

-

6.12.3.2 GET 311

-

6.13 Resource: csourceSubscriptions/{subscriptionId} 312

-

6.13.1 Description 312

-

6.13.2 Resource definition 312

-

6.13.3 Resource methods 312

-

6.13.3.1 GET 312

-

6.13.3.2 PATCH 313

-

6.13.3.3 DELETE 314

-

6.14 Resource: entityOperations/create 314

-

6.14.1 Description 314

-

6.14.2 Resource definition 315

-

6.14.3 Resource methods 315

-

6.14.3.1 POST 315

-

6.15 Resource: entityOperations/upsert 316

-

6.15.1 Description 316

-

6.15.2 Resource definition 316

-

6.15.3 Resource methods 317

-

6.15.3.1 POST 317

-

6.16 Resource: entityOperations/update 318

-

6.16.1 Description 318

-

6.16.2 Resource definition 319

-

6.16.3 Resource methods 319

-

6.16.3.1 POST 319

-

6.17 Resource: entityOperations/delete 320

-

6.17.1 Description 320

-

6.17.2 Resource definition 320

-

6.17.3 Resource methods 321

-

6.17.3.1 POST 321

-

6.18 Resource: temporal/entities/ 322

-

6.18.1 Description 322

-

6.18.2 Resource definition 322

-

6.18.3 Resource methods 323

-

6.18.3.1 POST 323

-

6.18.3.2 GET 323

-

6.19 Resource: temporal/entities/{entityId} 327

-

6.19.1 Description 327

-

6.19.2 Resource definition 327

-

6.19.3 Resource methods 327

-

6.19.3.1 GET 327

-

6.19.3.2 DELETE 330

-

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

-

6.20.1 Description 331

-

6.20.2 Resource definition 331

-

6.20.3 Resource methods 331

-

6.20.3.1 POST 331

-

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

-

6.21.1 Description 332

-

6.21.2 Resource definition 332

-

6.21.3 Resource methods 332

-

6.21.3.1 DELETE 332

-

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

-

6.22.1 Description 333

-

6.22.2 Resource definition 333

-

6.22.3 Resource methods 334

-

6.22.3.1 PATCH 334

-

6.22.3.2 DELETE 334

-

6.23 Resource: entityOperations/query 335

-

6.23.1 Description 335

-

6.23.2 Resource definition 335

-

6.23.3 Resource methods 335

-

6.23.3.1 POST 335

-

6.24 Resource: temporal/entityOperations/query 337

-

6.24.1 Description 337

-

6.24.2 Resource definition 337

-

6.24.3 Resource methods 338

-

6.24.3.1 POST 338

-

6.25 Resource: types/ 338

-

6.25.1 Description 338

-

6.25.2 Resource definition 339

-

6.25.3 Resource methods 339

-

6.25.3.1 GET 339

-

6.26 Resource: types/{type} 340

-

6.26.1 Description 340

-

6.26.2 Resource definition 340

-

6.26.3 Resource methods 340

-

6.26.3.1 GET 340

-

6.27 Resource: attributes/ 341

-

6.27.1 Description 341

-

6.27.2 Resource definition 341

-

6.27.3 Resource methods 341

-

6.27.3.1 GET 341

-

6.28 Resource: attributes/{attrId} 342

-

6.28.1 Description 342

-

6.28.2 Resource definition 342

-

6.28.3 Resource methods 342

-

6.28.3.1 GET 342

-

6.29 Resource: jsonldContexts/ 343

-

6.29.1 Description 343

-

6.29.2 Resource definition 343

-

6.29.3 Resource methods 343

-

6.29.3.1 POST 343

-

6.29.3.2 GET 344

-

6.30 Resource: jsonldContexts/{contextId} 345

-

6.30.1 Description 345

-

6.30.2 Resource definition 345

-

6.30.3 Resource methods 345

-

6.30.3.1 GET 345

-

6.30.3.2 DELETE 346

-

6.31 Resource: entityOperations/merge 347

-

6.31.1 Description 347

-

6.31.2 Resource definition 347

-

6.31.3 Resource methods 347

-

6.31.3.1 POST 347

-

6.32 Resource: entityMaps/{entityMapId} 349

-

6.32.1 Description 349

-

6.32.2 Resource definition 349

-

6.32.3 Resource methods 349

-

6.32.3.1 GET 349

-

6.32.3.2 PATCH 350

-

6.32.3.3 DELETE 350

-

6.33 Resource: info/sourceIdentity 351

-

6.33.1 Description 351

-

6.33.2 Resource definition 351

-

6.33.3 Resource methods 351

-

6.33.3.1 GET 351

-

6.34 Resource: entityMaps 352

-

6.34.1 Description 352

-

6.34.2 Resource definition 352

-

6.34.3 Resource methods 352

-

6.34.3.1 GET 352

-

6.34.3.2 POST 353

-

6.35 Resource: temporal/entityMaps 354

-

6.35.1 Description 354

-

6.35.2 Resource definition 354

-

6.35.3 Resource methods 354

-

6.35.3.1 GET 354

-

6.35.3.2 POST 355

-

6.36 Resource: snapshots 356

-

6.36.1 Description 356

-

6.36.2 Resource definition 356

-

6.36.3 Resource methods 356

-

6.36.3.1 POST 356

-

6.36.3.2 DELETE 357

-

6.37 Resource: snapshots/{snapshotId} 358

-

6.37.1 Description 358

-

6.37.2 Resource definition 358

-

6.37.3 Resource methods 358

-

6.37.3.1 GET 358

-

6.37.3.2 PATCH 359

-

6.37.3.3 DELETE 359

-

6.38 Resource: snapshots/{snapshotId}/clone 360

-

6.38.1 Description 360

-

6.38.2 Resource definition 360

-

6.38.3 Resource methods 360

-

6.38.3.1 POST 360

-

7 API MQTT Notification Binding 361

-

7.1 Introduction 361

-

7.2 Notification behaviour 361

-

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

-

A.1 Introduction 363

-

A.2 Entity identifiers 363

-

A.3 NGSI-LD namespace 363

-

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

-

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

-

C.1 Introduction 370

-

C.2 Entity Representation 370

-

C.2.1 Property Graph 370

-

C.2.2 Vehicle Entity 371

-

C.2.3 Parking Entity 384

-

C.2.4 @context 390

-

C.3 Context Source Registration 391

-

C.4 Context Subscription 391

-

C.5 HTTP REST API Examples 392

-

C.5.1 Introduction 392

-

C.5.2 Create Entity of Type Vehicle 392

-

C.5.2.1 HTTP Request 392

-

C.5.2.2 HTTP Response 392

-

C.5.3 Query Entities 392

-

C.5.3.1 Introduction 392

-

C.5.3.2 HTTP Request 393

-

C.5.3.3 HTTP Response 393

-

C.5.4 Query Entities (Pagination) 393

-

C.5.4.1 Introduction 393

-

C.5.4.2 HTTP Request 393

-

C.5.4.3 HTTP Response 393

-

C.5.5 Temporal Query 394

-

C.5.5.1 Introduction 394

-

C.5.5.2 HTTP Request #1 394

-

C.5.5.3 HTTP Response #1 394

-

C.5.5.4 HTTP Request #2 395

-

C.5.5.5 HTTP Response #2 395

-

C.5.6 Temporal Query (Simplified Representation) 395

-

C.5.6.1 Introduction 395

-

C.5.6.2 HTTP Request 395

-

C.5.6.3 HTTP Response 396

-

C.5.7 Retrieve Available Entity Types 396

-

C.5.7.1 Introduction 396

-

C.5.7.2 HTTP Request 396

-

C.5.7.3 HTTP Response 396

-

C.5.8 Retrieve Details of Available Entity Types 397

-

C.5.8.1 Introduction 397

-

C.5.8.2 HTTP Request 397

-

C.5.8.3 HTTP Response 397

-

C.5.9 Retrieve Available Entity Type Information 398

-

C.5.9.1 Introduction 398

-

C.5.9.2 HTTP Request 398

-

C.5.9.3 HTTP Response 398

-

C.5.10 Retrieve Available Attributes 399

-

C.5.10.1 Introduction 399

-

C.5.10.2 HTTP Request 399

-

C.5.10.3 HTTP Response 399

-

C.5.11 Retrieve Details of Available Attributes 399

-

C.5.11.1 Introduction 399

-

C.5.11.2 HTTP Request 399

-

C.5.11.3 HTTP Response 400

-

C.5.12 Retrieve Available Attribute Information 400

-

C.5.12.1 Introduction 400

-

C.5.12.2 HTTP Request 400

-

C.5.12.3 HTTP Response 401

-

C.5.13 Query Entities (Natural Language Filtering) 401

-

C.5.13.1 Introduction 401

-

C.5.13.2 HTTP Request 401

-

C.5.13.3 HTTP Response 401

-

C.5.14 Temporal Query (Aggregated Representation) 402

-

C.5.14.1 Introduction 402

-

C.5.14.2 HTTP Request 402

-

C.5.14.3 HTTP Response 402

-

C.5.15 Scope Queries 403

-

C.5.15.1 Introduction 403

-

C.5.15.2 HTTP Request 403

-

C.5.15.3 HTTP Response 403

-

C.5.16 Temporal Scope Queries 404

-

C.5.16.1 Introduction 404

-

C.5.16.2 HTTP Request 404

-

C.5.16.3 HTTP Response 404

-

C.6 Date Representation 406

-

C.7 @context utilization clarifications 407

-

C.8 Link header utilization clarifications 408

-

C.9 @context processing clarifications 410

-

C.10 ValueType datatype utilization clarifications 411

-

C.11 Entity with digital signature for a Property 411

-

Annex D (informative): Transformation Algorithms 413

-

D.1 Introduction 413

-

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

-

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

-

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

-

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

-

Annex F (informative): Conventions and syntax guidelines 417

-

Annex G (informative): Localization and Internationalization Support 418

-

G.0 Foreword 418

-

G.1 Introduction 418

-

G.1.0 Foreword 418

-

G.1.1 Associating an Entity with a Natural Language 418

-

G.1.2 Associating a Property with a Natural Language 418

-

G.1.3 Associating as equivalent entity 419

-

G.2 Natural Language Collation Support 419

-

G.2.0 Foreword 419

-

G.2.1 Maintain collations as metadata 420

-

G.2.2 Route language sensitive queries via a proxy 420

-

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

-

G.3.0 Foreword 420

-

G.3.1 Localizing Dates 420

-

Annex H (informative): Suggested actuation workflows 422

-

H.1 Actuators and feedback to the consumer 422

-

H.2 Architecture for actuation 422

-

H.3 Structure of Commands and additional Properties 423

-

H.3.0 Introduction 423

-

H.3.1 Property for listing available commands 424

-

H.3.2 Properties for command endpoints 424

-

H.4 Communication model 426

-

H.4.1 Possible communication models 426

-

H.4.2 Subscription/notification model 426

-

H.4.3 Forwarding model 427

-

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

-

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

-

Annex I (informative): Change history 432

-

History 435

- - diff --git a/API-html/1-intellectual-property-rights.html b/API-html/1-intellectual-property-rights.html deleted file mode 100644 index 708201fd250ced00b4ab5b2dc04371e62ffe8e79..0000000000000000000000000000000000000000 --- a/API-html/1-intellectual-property-rights.html +++ /dev/null @@ -1,1419 +0,0 @@ - - - - - - - -Intellectual Property Rights - - - - - - - - -

Intellectual Property Rights

-
-

Essential patents

-
-

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 IPR online database.

-

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.

-
-

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 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™, LTE™ and 5G™ logo 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.

- - diff --git a/API-html/10-tabapi-operation-definition.html b/API-html/10-tabapi-operation-definition.html deleted file mode 100644 index 2cc83b2f4944a99ad7a7ac66335f0153fda0f620..0000000000000000000000000000000000000000 --- a/API-html/10-tabapi-operation-definition.html +++ /dev/null @@ -1,14888 +0,0 @@ - - - - - - - -5 API Operation Definition - - - - - - - - -

5 API Operation Definition

-

5.1 Introduction

-

This clause defines data structures and operations of the NGSI-LD API. No specific binding is assumed. Clause 6 maps these operations and data types to the HTTP REST binding.

-
-
-

NOTE:

-
-
-

In UML diagrams dotted arrows denote a response to a request.

-
-
-

5.2 Data Types

-

5.2.1 Introduction

-

Implementations shall support the data types defined by the clauses below. For each member defined by each data type (including nested ones) a term shall be added to the Core @context, as mandated by clause 4.5.

-

None of the members described admit a null value directly, as when a JSON-LD processor encounters null, the associated entry or value is always removed when expanding the JSON-LD document.

-

However, in the context of a partial update or merge operation (see clauses 5.5.8 and 5.5.12), an NGSI-LD Null shall be used to indicate the removal of a target member, as explained in clause 4.5.0. In all other cases, implementations shall raise an error of type BadRequestData if an NGSI-LD Null value is encountered.

-

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

-

Non-normative JSON Schema [i.11] definitions of the referred data types are also available at [i.13].

-

The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [23], which extends the use of characters to Unicode characters [22] beyond the ASCII character set, enabling the support of languages other than English.

-

5.2.2 Common members

-

The JSON-LD representation of NGSI-LD Entity, Property, Relationship, Context Source Registration and Subscription can include the common members described by Table 5.2.2‑1.

-

Those members are read-only, and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-

In query or retrieve operations implementations shall only generate common members (Table 5.2.2‑1) when the Context Consumerexplicitly asks for their inclusion. Clause 6.3.11 defines the mechanism offered by the HTTP binding for such purpose.

-
-

Table 5.2.2-1: Common members of NGSI-LD elements

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-createdAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity creation timestamp. See clause 4.8. -
-deletedAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity deletion timestamp. See clause 4.8. It is only used in notifications reporting deletions and in the temporal representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) and LanguageProperties (clause 5.2.32) and VocabProperties (clause 5.2.35) and JsonProperties (clause 5.2.38). -
-modifiedAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity last modification timestamp. See clause 4.8. -
-

5.2.3 @context

-

When encoding NGSI-LD Entities, Context Source Registrations, Subscriptions and Notifications, as pure JSON-LD (MIME type “application/ld+json”),

-

an array (flattened to a single string if necessary), containing a user

-

@context

-

where present, and the core

-

@context (as described in clause 4.4) shall be included as a special member of the corresponding JSON-LD Object. Table 5.2.3‑1 gives a precise definition of this special member.

-
-

Table 5.2.3-1: JSON-LD @context tagged member

-
- ------- - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. -
-

5.2.4 Entity

-

This type represents the data needed to define an NGSI-LD Entity as mandated by clause 4.5.1.

-

The supported JSON members shall follow the requirements provided in Table 5.2.4‑1.

-
-

Table 5.2.4-1: NGSI-LD Entity data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Entity ID. -
-type -
-String or String[] -
-1 -
-Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. -
-
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Entity. See clause 4.22. -
-location -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-Default geospatial Property of an entity. See clause 4.7. -
-observationSpace -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-See clause 4.7. -
-operationSpace -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-See clause 4.7. -
-scope -
-String or String[] -
-See clause 4.18 -
-0..1 -
-Scope. -
- -
-Property or Property[] (see note 1) -
-See datatype definitions in clause 5.2.5 -
-0..N -
-Property as mandated by clause 4.5.2. -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperty as mandated by clause 4.5.2. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperty as mandated by clause 4.5.18. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperty as mandated by clause 4.5.24. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperty as mandated by clause 4.5.20. -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperty as mandated by clause 4.5.21. -
- -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationship as mandated by clause 4.5.3. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationship as mandated by clause 4.5.22. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId .

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId .

-
-
-
-

5.2.5 Property

-

This type represents the data needed to define a Property as mandated by clause 4.5.2.

-

The supported JSON members shall follow the requirements provided in Table 5.2.5‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute type member can be omitted as type=“Property” can be inferred from the presence of the value member. Furthermore, in the concise representation of a Property, the value member cannot be a GeoJSON Object (as defined in clause 4.7) as it would be interpreted as a GeoProperty (see clause 5.2.7).

-
-

Table 5.2.5-1: NGSI-LD Property data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Property” -
-1 -
-Node type. -
-value -
-Any JSON value as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1. -
-1 -
-Property Value. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Property. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the Property guaranteeing its integrity. See clause C.11 for an example. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-unitCode -
-String -
-As mandated by [15] -
-0..1 -
-Property Value’s unit code. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the Property Value. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
- -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the Property. -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the Property. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the Property. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the Property. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the Property. -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the Property. -
- -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the Property. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the Property. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.5-2) of the Property data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.5-2: Output only members of the NGSI-LD Property data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of Properties -
-0..1 -
-URI uniquely identifying a Property instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousValue -
-Any JSON value as defined by IETF RFC 8259 [6] -
-Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous Property Value. -
-

5.2.6 Relationship

-

This type represents the data needed to define a Relationship as mandated by clause 4.5.3.

-

The supported JSON members shall follow the requirements provided in Table 5.2.6‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute typemember can be omitted as type=“Relationship” can be inferred from the presence of the object member.

-
-

Table 5.2.6-1: NGSI-LD Relationship data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Relationship” -
-1 -
-Node type. -
-object -
-String or String[] -
-Valid URI or an Array of Valid URIs -
-1 -
-Relationship’s target object. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of target relationship objects. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Relationship. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the Relationship guaranteeing its integrity. -
-objectType -
-String or String[] -
-0..1 -
-Node Type of the Relationship’s target object. Both short hand string(s) (type name) or URI(s) are allowed. -
-
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
- -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the Relationship. -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the Relationship. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the Relationship. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the Relationship. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the Relationship. -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the Relationship. -
- -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the Relationship. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the Relationship. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.6-2) of the Relationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.6-2: Output only members of the NGSI-LD Relationship data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-entity -
-Entity or Entity[] (see note) -
-

See datatype definition in clause 5.2.4.

-

Only used in Linked Entity Retrieval, if the join=inline option is explicitly requested

-
-0..1 -
-An inline Entity obtained by Linked Entity Retrieval, corresponding to the Relationship’s target object. See clause 4.5.23.2. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of Relationships -
-0..1 -
-URI uniquely identifying a Relationship instance as mandated by clause 4.5.8. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousObject -
-String -
-Valid URI. Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous Relationship’s target object. -
-
-
-

NOTE:

-
-
-

one-to-N Relationships expand to an array of Entity elements, since there can be more than one target object URI specified.

-
-
-
-

5.2.7 GeoProperty

-

This type represents the data needed to define a GeoProperty.

-

The supported JSON members shall follow the requirements provided in Table 5.2.7‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute type member can be omitted as “GeoProperty” can be inferred from the presence of the value member holding a GeoJSON Geometry as mandated by clause 4.7.

-
-

Table 5.2.7-1: NGSI-LD GeoProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “GeoProperty” -
-1 -
-Node type. -
-value -
-JSON Object -
-As mandated by clause 4.7 -
-1 -
-Geolocation encoded as GeoJSON [8]. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the GeoProperty. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the GeoProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the GeoProperty Value. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
- -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of theGeoProperty. -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoPropertiesof theGeoProperty. -
-LanguageProperty or LanguageProperty[](see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguagePropertiesof theGeoProperty. -
-JsonProperty or JsonProperty -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the GeoProperty. -
-VocabProperty or VocabProperty[](see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabPropertiesof theGeoProperty. -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the GeoProperty. -
- -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of theGeoProperty. -
-ListRelationship or ListRelationship[](see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the GeoProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.7-2) of the GeoProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.7-2: Output only members of the NGSI-LD GeoProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of GeoProperties -
-0..1 -
-URI uniquely identifying a GeoProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousValue -
-Any JSON value as defined by IETF RFC 8259 [6] -
-Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous GeoProperty Value. -
-

5.2.8 EntityInfo

-

This type represents what Entities, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]) can be provided (by Context Sources).

-

The JSON members shall follow the indications provided in Table 5.2.8‑1. id takes precedence over idPattern.

-

Notice that Cardinality of type being 1 implies that it is not possible to register what Entities can be provided by a Context Source just by their id or idPattern (i.e. without specifying their type).

-
-

Table 5.2.8-1: EntityInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String or String[] -
-Fully Qualified Name of an Entity Type or the Entity Type name as a short-hand string. See clause 4.6.2 -
-1 -
-Entity Type (or JSON array, in case of Entities with multiple Entity Types). -
-id -
-String -
-Valid URI -
-0..1 -
-Entity identifier. -
-idPattern -
-String -
-Regular expression as per IEEE 1003.2™ [11] -
-0..1 -
-A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. -
-

5.2.9 CSourceRegistration

-

This type represents the data needed to register a new Context Source.

-

The supported JSON members shall follow the indications provided in Table 5.2.9‑1.

-
-

Table 5.2.9-1: CSourceRegistration data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-

Valid URI.

-

Unique registration identifier. (JSON-LD @id).

-
-0..1 -
-

Generated at creation time, if it is not provided, it will be assigned during registration process and returned to client.

-

It cannot be later modified in update operations.

-
-type -
-String -
-It shall be equal to “ContextSourceRegistration” -
-1 -
-

JSON-LD @type

-

Use reserved type for identifying Context Source Registration.

-
-endpoint -
-String -
-It shall be a dereferenceable URI -
-1 -
-Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD interface. -
-contextSourceInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to provide when contacting the registered Context Source. -
-
-information -
-RegistrationInfo[] -
-See data type definition in clause 5.2.10. Empty array (0 length) is not allowed -
-1 -
-Describes the Entities, Properties and Relationships for which the Context Source may be able to provide information. -
-contextSourceAlias -
-String -
-Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] -
-0..1 -
-

A previously retrieved unique id for a registered Context Source which is used to identify loops.

-

In the multi-tenancy use case (see clause 4.14), this id shall be used to identify a specific Tenant within a registered Context Source.

-
-description -
-String -
-Non-empty string -
-0..1 -
-A description of this Context Source Registration. -
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of Attributes that the Context Source can provide, defined as per clause 4.5.5. -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Provides an expiration date. When passed the Context Source Registration will become invalid and the Context Source might no longer be available. -
-location -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Location for which the Context Sourcemay be able to provide information. -
-
-management -
-

Registration

-

Management

-

Info

-
-See data type definition in clause 5.2.34 -
-0..1 -
-Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. -
-managementInterval -
-TimeInterval -
-See data type definition in clause 5.2.11 -
-0..1 -
-If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The managementInterval specifies the time interval for which the Context Source can provide Entity information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched against the managementInterval for overlap. -
-mode -
-String -
-

It shall be one of:

-

“inclusive”,“exclusive”,“redirect” or “auxiliary”

-

The mode is assumed to be “inclusive” if not explicitly defined

-
-0..1 -
-The definition of the mode of distributed operation (see clause 4.3.6) supported by the registered Context Source. -
-observationInterval -
-TimeInterval -
-See data type definition in clause 5.2.11 -
-0..1 -
-If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The observationInterval specifies the time interval for which the Context Source can provide Entity information as specified by the observedAt Temporal Property. A temporal query based on the observedAt Temporal Property, which is the default, is matched against the observationInterval for overlap. -
-observationSpace -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Geographic location that includes the observation spaces of all entities as specified by their respective observationSpace GeoProperty for which the Context Source may be able to provide information. -
-
-operations -
-String[] -
-Entries are limited to the named API operations and named operation groups (see clause 4.20) -
-0..1 -
-

The definition limited subset of API operations supported by the registered Context Source.

-

If undefined, the default set of operations is “federationOps” (see clause 4.20).

-
-operationSpace -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Geographic location that includes the operation spaces of all entities as specified by their respective operationSpace GeoProperty for which the Context Source may be able to provide information. -
-
-refreshRate -
-String -
-String representing a duration in ISO 8601 [17] format -
-0..1 -
-

An indication of the likely period of time to elapse between updates at this registered endpoint.

-

Brokers may optionally use this information to help implement caching.

-
-registrationName -
-String -
-Non-empty string -
-0..1 -
-A name given to this Context Source Registration. -
-scope -
-

String or

-

String[]

-
-Scope(s) -
-0..1 -
-Scopes (see clause 4.18) for which the Context Source has Entities. -
-tenant -
-String -
-0..1 -
-Identifies the Tenant that has to be specified in all requests to the Context Source that are related to the information registered in this Context Source Registration. If not present, the default Tenant is assumed. Should only be present in systems supporting multi-tenancy. -
-
-

The members (defined by Table 5.2.9-2) of the CSourceRegistration data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.9-2: Additional members of the CSourceRegistration data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-lastFailure -
-String -
-DateTime(clause4.6.3) -
-0..1 -
-Timestamp corresponding to the instant whenthe last distributed operation resulting in a failure (forinstance, in the HTTP binding, an HTTP response code other than 2xx) was returned. -
-status -
-String -
-

Allowed values:

-

“ok”

-

“failed”

-
-0..1 -
-Read-only., Status of the Registration. It shall be “ok” if the last attempt to perform a distributed operation succeeded. It shall be “failed” if the last attempt to perform a distributed operation failed. -
-timesFailed -
-Number -
-0 or greater value -
-0..1 -
-Number of times that the registration triggered a distributed operation request that failed. -
-timesSent -
-Number -
-0 or greater value -
-0..1 -
-Number of times that the registration triggered a distributed operation, including failed attempts. -
-lastSuccess -
-String -
-DateTime(clause4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last successfully distributed operation was sent. Created on first successful operation. -
-

5.2.10 RegistrationInfo

-

The supported JSON members shall follow the requirements provided in Table 5.2.10‑1.

-
-

Table 5.2.10-1: RegistrationInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entities -
-EntityInfo[] -
-See data type definition in clause 5.2.8. Empty array (0 length) is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the entities for which the CSource may be able to provide information. -
-propertyNames -
-String[] -
-Property names as short hand strings or URIs. Empty array is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the Properties that the CSource may be able to provide. -
-relationshipNames -
-String[] -
-Relationship names as short hand strings or URIs. Empty array is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the Relationships that the CSource may be able to provide. -
-

At least one element of RegistrationInfo shall be present.

-

5.2.11 TimeInterval

-

The supported JSON members shall follow the requirements provided in Table 5.2.11‑1.

-
-

Table 5.2.11-1: TimeInterval data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-startAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Describes the start of the time interval -
-endAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Describes the end of the time interval. If not present the interval is open -
-

5.2.12 Subscription

-

This datatype represents a Context Subscription.

-

The supported JSON members shall follow the requirements provided in Table 5.2.12‑1.

-
-

Table 5.2.12-1: Subscription data type definition

-
- -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-0..1 -
-

Subscription identifier (JSON-LD @id). Generated at creation time, if it is not provided, it will be assigned during subscription process and returned to client.

-

It cannot be later modified in update operations.

-
-type -
-String -
-It shall be equal to “Subscription” -
-1 -
-JSON-LD @type. -
-entities -
-EntitySelector[] -
-

See data type definition in clause 5.2.33. Empty array (0 length) is not allowed.

-

Mandatory if timeInterval is present, unless the execution of the request is limited to local scope (see clause 5.5.13)

-
-0..1 -
-Entities subscribed. -
-notification -
-NotificationParams -
-See data type definition in clause 5.2.14 -
-1 -
-Notification details. -
-notificationTrigger -
-String[] -
-Valid notification triggers are “entityCreated”,“entityUpdated”,“entityDeleted”,“attributeCreated”,“attributeUpdated”,“attributeDeleted” -
-0..1 -
-The notification triggers listed indicate what kind of changes shall trigger a notification. If not present, the default is the combination “attributeCreated” and “attributeUpdated”. “entityUpdated” is equivalent to the combination “attributeCreated”, “attributeUpdated” and “attributeDeleted”. -
-watchedAttributes -
-String[] -
-

Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed.

-

if timeInterval is present it shall not appear (0 cardinality)

-
-0..1 -
-Watched Attributes (Properties or Relationships). If not defined it means any Attribute. -
-q -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Query that shall be met by subscribed entities in order to trigger the notification. -
-geoQ -
-GeoQuery -
-See data type definition in clause 5.2.13 -
-0..1 -
-Geoquery that shall be met by subscribed entities in order to trigger the notification. -
-scopeQ -
-String -
-See clause 4.19 -
-0..1 -
-Scope query. -
-temporalQ -
-TemporalQuery -
-See data type definition in clause 5.2.21 -
-0..1 -
-Temporal Query to be used only in Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal information. -
-csf -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Context source filter that shall be met by Context Source Registrations describing Context Sources to be used for Entity Subscriptions. -
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-description -
-String -
-0..1 -
-Subscription description. -
-
-expandValues -
-String -
-Comma separated list of attribute names -
-0..1 -
-Values of the identified attributes should be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-Expiration date for the subscription. -
-isActive -
-Boolean -
-true by default -
-0..1 -
-Allows clients to temporarily pause the subscription by making it inactive. true indicates that the Subscription is under operation. false indicates that the subscription is paused, and notifications shall not be delivered. -
-jsonKeys -
-String -
-Comma separate list of attribute names -
-0..1 -
-Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-jsonldContext -
-String -
-Dereferenceable URI -
-0..1 -
-The dereferenceable URI of the JSON-LD @context to be used when sending a notification resulting from the subscription. If not provided, the @context used for the subscription shall be used as a default. -
-lang -
-String -
-A natural language filter in the form of a IETF RFC 5646 [28] language code -
-0..1 -
-Language filter to be applied to the query (clause 4.15). -
-localOnly -
-Boolean -
-0..1 -
-If localOnly=true then the subscription only pertains to the Entities stored locally. In case the Subscription pertains to a Snapshot it is always local, regardless of whether localOnly is set to true or not. -
-
-ngsildConformance -
-String -
-A semantically versioned string in the form major.minor, which conforms to a version of the NGSI-LD specification -
-0..1 -
-If provided the notification shall undergo a backwards compatibility operation as defined by clause 4.3.6.8 and be amended to conform to the supplied version of the NGSI-LD specification. -
-splitEntities -
-Boolean -
-default decided by implementation; it should be configurable. The parameter does not apply in case localOnly is true. -
-0..1 -
-If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. -
-subscriptionName -
-String -
-0..1 -
-A (short) name given to this Subscription. -
-
-throttling -
-Number -
-Greater than 0. Fractional values are allowed. If timeInterval is present it shall not appear (0 cardinality) -
-0..1 -
-Minimal period of time in seconds which shall elapse between two consecutive notifications. -
-timeInterval -
-Number -
-

Greater than 0

-

if watchedAttributes is present it shall not appear (0 cardinality)

-
-0..1 -
-Indicates that a notification shall be delivered periodically regardless of attribute changes. Actually, when the time interval (in seconds) specified in this value field is reached. -
-

At least one of (a) entities or (b) watchedAttributes shall be present, unless the member localOnlyis set to true, in which case the execution of the request is limited to local scope (see clause 5.5.13).

-

The members (defined by Table 5.2.12-2) of the Subscription data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.12-2: Additional members of the Subscription data type

-
- ------- - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-status -
-String -
-

Allowed values:

-

“active”

-

“paused”

-

“expired”

-
-0..1 -
-Read-only. Provided by the system when querying the details of a subscription. -
-

5.2.13 GeoQuery

-

This datatype represents a geoquery used for Subscriptions.

-

The supported JSON members shall follow the requirements provided in Table 5.2.13‑1.

-
-

Table 5.2.13-1: GeoQuery data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-coordinates -
-JSON Array or String -
-A JSON Array coherent with the geometry type as per IETF RFC 7946 [8] -
-1 -
-Coordinates of the reference geometry. For the sake of JSON-LD compatibility It can be encoded as a string as described in clause 4.7.1. -
-geometry -
-String -
-A valid GeoJSON [8] geometry type excepting GeometryCollection -
-1 -
-Type of the reference geometry. -
-georel -
-String -
-A valid geo-relationship as defined by clause 4.10 -
-1 -
-Geo-relationship (“near”, “within”, etc.). -
-geoproperty -
-String -
-Attribute name as short hand string or URI -
-0..1 -
-Specifies the GeoProperty to which the GeoQuery is to be applied. If not present, the default GeoProperty is location. -
-

5.2.14 NotificationParams

-

5.2.14.1 NotificationParams data type definition

-

This datatype represents the parameters that allow to convey the details of a notification.

-

The supported JSON members shall follow the requirements provided in Table 5.2.14.1‑1.

-
-

Table 5.2.14.1-1: NotificationParams data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-endpoint -
-Endpoint -
-See data type definition in clause 5.2.15 -
-1 -
-Notification endpoint details. -
-attributes -
-String[] -
-Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed -
-0..1 -
-

A synonym for pick, except that id, type, scope are not allowed. Deprecated

-

Attribute names to be included in the notification payload body. If undefined it will mean all Attributes.

-
-format -
-String -
-It shall be one of: “normalized”, “concise”, “simplified” (or its synonym “keyValues”) -
-0..1 -
-Conveys the representation format of the entities delivered at notification time. By default, it will be in the normalized format. -
-join -
-String -
-It shall be one of: “flat”, “inline”, “@none” -
-0..1 -
-

String representing the type of Linked Entity retrieval to apply.

-

By default, it will be “@none”.

-
-joinLevel -
-Number -
-Positive Integer -
-0..1 -
-Depth of Linked Entity retrieval to apply. Default is 1. Only applicable if join parameter is “flat”, or “inline”. -
-omit -
-String[] -
-Entity member (“id”, “type”, “scope”or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, the specified Entity members are removed from each Entity within the payload. -
-pick -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name as a valid attribute projection language string as per clause 4.21). Empty array (0 length) is not allowed -
-0..1 -
-When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. -
-showChanges -
-Boolean -
-false by default -
-0..1 -
-

If true the previous value (previousValue) of Properties or languageMap (previousLanguageMap) of Language Properties or object (previousObject) of Relationships is provided in addition to the current one. This requires that it exists, i.e. in case of modifications and deletions, but not in the case of creations.

-

showChanges cannot be true in case format is “keyValues”.

-
-sysAttrs -
-Boolean -
-false by default -
-0..1 -
-If true, the system generated attributes createdAt and modifiedAt and the system attribute expiresAt are included in the response payload body, in the case of a deletion also deletedAt. -
-

5.2.14.2 Output only members

-

The following output only members (defined by Table 5.2.14.2-1) of the NotificationParams data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-

In query or retrieve operations involving Subscriptions, implementations shall generate them as part of their representation.

-
-

Table 5.2.14.2-1: Output only members of the NotificationParams data structure

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-lastFailure -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last notification resulting in failure (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. Provided by the system when querying the details of a subscription. -
-lastNotification -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last notification has been sent. Provided by the system when querying the details of a subscription. -
-lastSuccess -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last successful (200 OK response) notification has been sent. Provided by the system when querying the details of a subscription. -
-status -
-String -
-

Allowed values:

-

“ok”, “failed”

-
-0..1 -
-Status of the Notification. It shall be “ok” if the last attempt to notify the subscriber succeeded. It shall be “failed” if the last attempt to notify the subscriber failed. -
-timesFailed -
-Number -
-Greater than 0 -
-0..1 -
-Number of times an unsuccessful response (or timeout) has been received when delivering the notification. Provided by the system when querying the details of a subscription. -
-timesSent -
-Number -
-Greater than 0 -
-0..1 -
-Number of times that the notification has been sent. Provided by the system when querying the details of a subscription. -
-

5.2.15 Endpoint

-

This datatype represents the parameters that are required in order to define an endpoint for notifications. This can include, in addition the endpoint’s URI, a generic{key, value} array, named receiverInfo, which contains, in a generalized form, whatever extra information the Context Broker shall convey to the receiver in order for the Context Broker to successfully communicate with receiver (e.g. Authorization material), or for the receiver to correctly interpret the received content (e.g. the Link URL to fetch an @context). Additionally, it can include another generic{key, value} array, named notifierInfo, which contains the configuration that the Context Broker needs to know in order to correctly set up the communication channel towards the receiver (e.g. MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in clause 7.2).

-

The supported JSON members shall follow the indications provided in Table 5.2.15‑1.

-
-

Table 5.2.15-1: Endpoint data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-uri -
-String -
-Dereferenceable URI -
-1 -
-URI which conveys the endpoint which will receive the notification. -
-accept -
-String -
-

MIME type. It shall be one of:

-

“application/json”

-

“application/ld+json”

-

“application/geo+json”

-
-0..1 -
-Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). If not present, default is “application/json”. -
-cooldown -
-Number -
-Greater than 0 -
-0..1 -
-Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent. -
-notifierInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to set up the communication channel. -
-
-receiverInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to the receiver. -
-
-timeout -
-Number -
-Greater than 0 -
-0..1 -
-Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. The NGSI-LD system can override this value. This only applies if the binding protocol always returns a response. -
-

5.2.16 BatchOperationResult

-

This datatype represents the result of a batch operation.

-

The supported JSON members shall follow the indications provided in Table 5.2.16‑1.

-
-

Table 5.2.16-1: BatchOperationResult data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-errors -
-BatchEntityError[] -
-1 -
-One array item per Element in error. Empty Array if no errors happened. -
-
-success -
-String[] -
-Array of valid URIs -
-1 -
-Array of Entity IDs corresponding to the Elements that were successfully treated by the concerned operation. Empty Array if no Element was successfully treated. -
-

5.2.17 BatchEntityError

-

This datatype represents an error raised (associated to a particular Entity) during the execution of a batch or distributed operation.

-

The supported JSON members shall follow the indications provided in Table 5.2.17‑1.

-
-

Table 5.2.17-1: BatchEntityError data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entityId -
-String -
-Valid URI -
-1 -
-Entity ID corresponding to the Entity in error. -
-error -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-One instance per Entity in error. -
-
-registrationId -
-String -
-Valid URI -
-0..1 -
-Registration Id corresponding to a failed distributed operation (optional). -
-

5.2.18 UpdateResult

-

This datatype represents the result of Attribute update (append or update) operations in the NGSI-LD API regardless of whether local or distributed.

-

The supported JSON members shall follow the indications provided in Table 5.2.18‑1.

-
-

Table 5.2.18-1: UpdateResult data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-notUpdated -
-NotUpdatedDetails[] -
-See clause 5.2.19 -
-1 -
-List which contains the Attributes (represented by their name) that were not updated, together with the reason for not being updated. -
-updated -
-String[] -
-1 -
-List of Attributes (represented by their name) that were appended or updated. -
-
-

5.2.19 NotUpdatedDetails

-

This datatype represents additional information provided by an implementation when an Attribute update did not happen. See also clause 5.2.18.

-

The supported JSON members shall follow the indications provided in Table 5.2.19‑1.

-
-

Table 5.2.19-1: NotUpdatedDetails data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-attributeName -
-String -
-1 -
-Attribute name. -
-
-reason -
-String -
-1 -
-Reason for not having changed such Attribute. -
-
-registrationId -
-String -
-Valid URI -
-0..1 -
-Registration Id corresponding to a failed distributed operation (optional). -
-

5.2.20 EntityTemporal

-

This datatype represents the Temporal Evolution of an Entity.

-

This is the same datatype as mandated by clause 5.2.4 with the only deviation that the representation of Properties and Relationships shall be the temporal one, as defined in clauses 4.5.7 and 4.5.8. Alternatively it is possible to specify the EntityTemporal by using the “Simplified temporal representation of an Entity”, as defined in clause 4.5.9.

-

5.2.21 TemporalQuery

-

This datatype represents a temporal query.

-

The supported JSON members shall follow the requirements provided in Table 5.2.21‑1.

-
-

Table 5.2.21-1: TemporalQuery data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-timeAt -
-String representing the timeAt parameter as defined by clause 4.11 -
-It shall be a DateTime -
-1 -
-
-timerel -
-String -
-Allowed values: “before”, “after” and “between” -
-1 -
-Represents the temporal relationship as defined by clause 4.11. -
-aggrMethods -
-Comma separated list of string -
-It shall be 1 if aggregatedValues is present in the options parameter -
-0..1 -
-Each String represents an aggregation method, as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-
-endTimeAt -
-String representing the endTimeAt parameter as defined by clause 4.11 -
-It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between” -
-0..1 -
-
-lastN -
-Positive integer -
-0..1 -
-Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. -
-
-timeproperty -
-String representing a Temporal Property name -
-Allowed values: “observedAt”, “createdAt”, “modifiedAt”and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8) -
-0..1 -
-
-

5.2.22 KeyValuePair

-

This datatype represents the optional information that is required when contacting an endpoint for notifications.

-

The supported members shall follow the indications provided in Table 5.2.22‑1. They are intended to represent a key/value pair.

-

Example optional information includes additional HTTP Headers such as:

-
- -
-
-

Table 5.2.22-1: KeyValuePair data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-key -
-String -
-Binding-dependent -
-1 -
-The key of the key/value pair. -
-value -
-String -
-Binding-dependent -
-1 -
-The value of the key/value pair. -
-

5.2.23 Query

-

This datatype represents the information that is required in order to convey a query when a “Query Entities” operation or a “Query Temporal Evolution of Entities” operation is to be performed (as per clauses 5.7.2 and 5.7.4, respectively).

-

The supported JSON members shall follow the requirements provided in Table 5.2.23‑1.

-
-

Table 5.2.23-1: Query data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Query” -
-1 -
-JSON-LD @type -
-entities -
-EntitySelector[] -
-See data type definition in clause 5.2.33. Empty array (0 length) is not allowed -
-0..1 -
-Entity IDs, id pattern and Entity types that shall be matched by Entities in order to be retrieved. -
-q -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Query that shall be matched by Entities in order to be retrieved. -
-geoQ -
-GeoQuery -
-See data type definition in clause 5.2.13 -
-0..1 -
-Geoquery that shall be matched by Entities in order be retrieved. -
-scopeQ -
-String -
-See clause 4.19 -
-0..1 -
-Scope query. -
-temporalQ -
-TemporalQuery -
-See data type definition in clause 5.2.21 -
-0..1 -
-Temporal Query to be present only for “Query Temporal Evolution of Entities” operation (clause 5.7.4). -
-attrs -
-String[] -
-

Attribute name as short hand strings or URIs.

-

Empty array (0 length) is not allowed

-
-0..1 -
-

A synonym for a combination of the pick andq members. Deprecated

-

List of Attributes that shall be matched by Entities in order to be retrieved. If not present all Attributes will be retrieved.

-
-omit -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, the specified Entity members are removed from each Entity within the payload. -
-pick -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. -
-aggrParams -
-AggregationParams -
-See data type definition in clause 5.2.44. -
-0..1 -
-

Aggregation parameters required for supporting aggregation methods in to be present only for “QueryTemporal Evolution of Entities” operation (clause 5.7.4).

-

Only applicable if “aggregatedValues” is present in theformat or options parameter.

-
-csf -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Context source filter that shall be matched by Context Source Registrations describing Context Sources to be used for retrieving Entities. -
-containedBy -
-String[] -
-Comma separated list of URIs. Empty array (0 length) is not allowed -
-0..1 -
-

List of entity ids which have previously been encountered whilst retrieving the Entity Graph.

-

Only applicable if joinLevel is present.

-

Only applicable for the “Retrieve Entity” (clause 5.7.1) and “Query Entities” operations (clause 5.7.2).

-
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-expandValues -
-String -
-Comma separated list of attribute names -
-0..1 -
-Values of the identified attributes should be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-
-entityMapLifetime -
-String -
-String representing a duration in ISO 8601 [17] format -
-0..1 -
-Suggested duration for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-jsonKeys -
-String -
-Comma separate list of attribute names -
-0..1 -
-Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-join -
-String -
-It shall be one of: “flat”, “inline”, “@none” -
-0..1 -
-

String representing the type of Linked Entity retrieval to apply.

-

By default, it will be “@none”.

-
-joinLevel -
-Number -
-Positive Integer -
-0..1 -
-Depth of Linked Entity retrieval to apply. Default is 1. Only applicable if join parameter is “flat”, or “inline”. -
-lang -
-String -
-A natural language filter in the form of a IETF RFC 5646 [28] language code -
-0..1 -
-Language filter to be applied to the query (clause 4.15). -
-ordering -
-OrderingParams -
-See data type definition in clause 5.2.43 -
-0..1 -
-

When defined, the Entities returned in the payload shall be ordered according to the members defined.

-

This only applies if the operation is limited to the local scope.

-
-splitEntities -
-Boolean -
-default decided by implementation; it should be configurable. The parameter does not apply in case the parameter local is true or the query applies to a Snapshot -
-0..1 -
-If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. -
-

5.2.24 EntityTypeList

-

This type represents the data needed to define the entity type list representation as mandated by clause 4.5.10.

-

The supported JSON members shall follow the requirements provided in Table 5.2.24‑1.

-
-

Table 5.2.24-1: NGSI-LD EntityTypeList data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-URI that is unique within the system scope. Identifier for the entity type list. -
-type -
-String -
-It shall be equal to “EntityTypeList” -
-1 -
-JSON-LD @type. -
-typeList -
-String[] -
-1 -
-List containing the entity type names. -
-
-

5.2.25 EntityType

-

This type represents the data needed to define the elements of the detailed entity type list representation as mandated by clause 4.5.11.

-

The supported JSON members shall follow the requirements provided in Table 5.2.25‑1.

-
-

Table 5.2.25-1: NGSI-LD EntityType data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Fully Qualified Name (FQN) of the entity type being described. -
-type -
-String -
-It shall be equal to “EntityType” -
-1 -
-JSON-LD @type. -
-attributeNames -
-String[] -
-1 -
-List containing the names of attributes that instances of the entity type can have. -
-
-typeName -
-String -
-1 -
-Name of the entity type, short name if contained in @context. -
-
-

5.2.26 EntityTypeInfo

-

This type represents the data needed to define the detailed entity type information representation as mandated by clause 4.5.12.

-

The supported JSON members shall follow the requirements provided in Table 5.2.26‑1.

-
-

Table 5.2.26-1: NGSI-LD EntityTypeInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Fully Qualified Name (FQN) of the entity type being described. -
-type -
-String -
-It shall be equal to “EntityTypeInfo” -
-1 -
-JSON-LD @type. -
-attributeDetails -
-Attribute[] -
-See data type definition in clause 5.2.28. Attribute with only the elements “id”, “type”, “attributeName” and “attributeTypes” -
-1 -
-List of attributes that entity instances with the specified entity type can have. -
-entityCount -
-Number -
-Unsigned integer -
-1 -
-Number of entity instances of this entity type. -
-typeName -
-String -
-1 -
-Name of the entity type, short name if contained in @context. -
-
-

5.2.27 AttributeList

-

This type represents the data needed to define the attribute list representation as mandated by clause 4.5.13.

-

The supported JSON members shall follow the requirements provided in Table 5.2.27‑1.

-
-

Table 5.2.27-1: NGSI-LD AttributeList data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-URI that is unique within the system scope. Identifier for the attribute list. -
-type -
-String -
-It shall be equal to “AttributeList” -
-1 -
-JSON-LD @type. -
-attributeList -
-String[] -
-1 -
-List containing the attribute names. -
-
-

5.2.28 Attribute

-

This type represents the data needed to define the attribute information needed as:

-
- -
-

The supported JSON members shall follow the requirements provided in Table 5.2.28‑1.

-
-

Table 5.2.28-1: NGSI-LD Attribute data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Full URI of attribute name. -
-type -
-String -
-It shall be equal to “Attribute” -
-1 -
-JSON-LD @type. -
-attributeName -
-String -
-1 -
-Name of the attribute, short name if contained in @context. -
-
-attributeCount -
-Number -
-Unsigned integer -
-0..1 -
-Number of attribute instances with this attribute name. -
-attributeTypes -
-String[] -
-0..1 -
-List of attribute types (e.g. Property, Relationship, GeoProperty) for which entity instances exist, which contain an attribute with this name. -
-
-typeNames -
-String[] -
-0..1 -
-List of entity type names for which entity instances exist containing attributes that have the respective name. -
-
-

5.2.29 Feature

-

This data type represents a spatially bounded Entity in GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members shall follow the requirements provided in Table 5.2.29‑1.

-
-

Table 5.2.29-1: Feature data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Entity ID. -
-type -
-String -
-It shall be equal to “Feature” -
-1 -
-GeoJSON Type. -
-geometry -
-GeoJSON Object -
-The value field from the matching GeoProperty (as specified in clause 4.5.16) or null -
-1 -
-null if no matching GeoProperty. -
-properties -
-FeatureProperties -
-See data type definition -
-1 -
-List of attributes as mandated by clause 5.2.31. -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [26]). -
-

5.2.30 FeatureCollection

-

This data type represents a list of spatially bounded Entities in GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members shall follow the requirements provided in Table 5.2.30‑1.

-
-

Table 5.2.30-1: FeatureCollection data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “FeatureCollection” -
-1 -
-GeoJSON Type. -
-features -
-Feature[] -
-See data type definition -
-1..N -
-In the case that no matches are found, features will be an empty array. -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [26]). -
-

5.2.31 FeatureProperties

-

This data type represents the type and the associated attributes (Properties and Relationships) of an Entity in GeoJSON format.

-
-

Table 5.2.31-1: FeatureProperties data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String or String[] -
-Entity Type -
-1 -
-Entity Type (or JSON array, in case of Entities with multiple Entity Types). Both short hand string (type name) or URI are allowed. -
- -
-Property or Property[], see note 1 -
-See data type definition in clause 5.2.5 -
-0..N -
-Property as mandated by clause 4.5.2. -
-GeoProperty or GeoProperty[], see note 1 -
-See datatype definition in clause  5.2.7 -
-0..N -
-GeoProperty as mandated by clause 4.5.2. -
-LanguageProperty or LanguageProperty[], see note 1 -
-See datatype definition in clause  5.2.32 -
-0..N -
-LanguageProperty as mandated by clause 4.5.18. -
-JsonProperty or JsonProperty[] see note 1 -
-See datatype definition in clause  5.2.38 -
-0..N -
-JsonProperties as mandated by clause 4.5.24. -
-VocabProperty or VocabProperty[], see note 1 -
-See datatype definition in clause  5.2.35 -
-0..N -
-VocabProperty as mandated by clause 4.5.20. -
-ListProperty or ListProperty[], see note 1 -
-See datatype definition in clause  5.2.36 -
-0..N -
-ListProperty as mandated by clause 4.5.21. -
- -
-Relationship or Relationship[], see note 2 -
-See data type definition in clause  5.2.6 -
-0..N -
-Relationship as mandated by clause 4.5.3. -
-ListRelationship or ListRelationship[], see note 2 -
-See datatype definition in clause  5.2.37 -
-0..N -
-ListRelationship as mandated by clause 4.5.22. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

5.2.32 LanguageProperty

-

This type represents the data needed to define a LanguageProperty as mandated by clause 4.5.18. Note that in case of concise representation, the type can be omitted (see clause 4.5.18.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.32‑1.

-
-

Table 5.2.32-1: NGSI-LD LanguageProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-string -
-It shall be equal to “LanguageProperty” -
-1 -
-Node type. -
-languageMap -
-JSON object -
-A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [28] language codes and whose values shall be JSON strings or arrays of JSON strings -
-1 -
-String Property Values defined in multiple natural languages. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the LanguageProperty. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the LanguageProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-It shall be equal to “langString” (see note 1) -
-0..1 -
-The native JSON-LD @type for the languageMap attribute. It shall align with the RDF datatype [34]. -
- -
-Property or Property[] (see note 2) -
-See datatype definition in clauses 5.2.5 -
-0..N -
-Properties of the LanguageProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 2)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the LanguageProperty. -
-LanguageProperty or LanguageProperty[] (see note 2) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the LanguageProperty. -
-JsonProperty or JsonProperty[] (see note 2) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the LanguageProperty. -
-VocabProperty or VocabProperty[] (see note 2) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the LanguageProperty. -
-

ListProperty

-

or ListProperty[] (see note 2)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the LanguageProperty. -
- -
-

Relationship

-

or Relationship[] (see note 3)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the LanguageProperty. -
-ListRelationship or ListRelationship[] (see note 3) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the LanguageProperty. -
-
-
-

NOTE 1:

-
-
-

The assigned @type for language tagged strings is datatype URI: http://www.w3.org/1999/02/22-rdf-syntax-ns#langString [34].

-
-
-
-
-

NOTE 2:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 3:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.32-2) of the LanguageProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.32-2: Output only members of the NGSI-LD LanguageProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of LanguageProperties -
-0..1 -
-URI uniquely identifying a LanguageProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousLanguageMap -
-JSON object -
-

A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [28] language codes and whose values shall be JSON strings.

-

Only used in Notifications, if the showChanges option is explicitly requested

-
-0..1 -
-Previous Language Property’s languageMap. -
-

5.2.33 EntitySelector

-

This type selects which entity or group of entities are queried or subscribed to by Context Consumers. Entities can be specified by their id, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]).

-

The JSON members shall follow the indications provided in Table 5.2.33‑1. id takes precedence over idPattern.

-
-

Table 5.2.33-1: EntitySelector data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String -
-A valid type selection string as per clause 4.17. To indicate a request for all Entities (with implied local scope), “*” is also allowed as a value. -
-1 -
-Selector of Entity Type(s); If type is specified as “*”, implying local scope, local scope shall not be explicitly set to be false (clause 5.5.13) for the execution of the corresponding operation. -
-id -
-String or String[] -
-Valid URI(s) -
-0..1 -
-Entity identifier(s). -
-idPattern -
-String -
-Regular expression as per IEEE 1003.2™ [11] -
-0..1 -
-A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. -
-

5.2.34 RegistrationManagementInfo

-

This type represents the data to alter the default behaviour of a Context Broker when making a distributed operation request to a registered Context Source. The supported JSON members shall follow the indications provided in Table 5.2.34-1. Brokers may override these recommendations.

-
-

Table 5.2.34-1: RegistrationManagementInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-cacheDuration -
-String -
-String representing a duration in ISO 8601 [17] format -
-0..1 -
-

Minimal period of time which shall elapse between two consecutive context information consumption operations (as defined in clause 5.7) related to the same context data will occur.

-

If the cacheDuration latency period has not been reached, a cached value for the entity or its attributes shall be returned where available.

-
-cooldown -
-Number -
-Greater than 0 -
-0..1 -
-

Minimum period of time in milliseconds which shall elapse before attempting to make a subsequent forwarded request to the same endpoint after failure.

-

If requests are received before the cooldown period has expired, a timeout error response for the registration is automatically returned.

-
-localOnly -
-Boolean -
-0..1 -
-

If localOnly=true then distributed operations associated to this Context Source Registration will act only on data held directly by the registered Context

-

Source itself (see clause 4.3.6.4).

-
-
-timeout -
-Number -
-Greater than 0 -
-0..1 -
-Maximum period of time in milliseconds which may elapse before a forwarded request is assumed to have failed. -
-

5.2.35 VocabProperty

-

This type represents the data needed to define a VocabProperty as mandated by clause 4.5.20. In case of concise representation, the type can be omitted (see clause 4.5.20.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.35‑1.

-
-

Table 5.2.35-1: NGSI-LD VocabProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “VocabProperty” -
-1 -
-Node type. -
-vocab -
-String or string[] -
-1 -
-String Values which shall be type coerced to URIs based on the supplied @context. -
-
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the VocabProperty. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the VocabProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the vocab attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
- -
-

Property

-

or Property[] (see note 1)

-
-See datatype definitions in clauses 5.2.5 -
-0..N -
-Properties of the VocabProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the VocabProperty. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the VocabProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the VocabProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the VocabProperty. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the VocabProperty. -
- -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the VocabProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the VocabProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.35-2) of the VocabProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.35-2: Output only members of the NGSI-LD VocabProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of VocabProperties -
-0..1 -
-URI uniquely identifying a VocabProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousVocab -
-String or String[] -
-Only used in Notifications -
-0..1 -
-Previous VocabProperty’s vocab. -
-

5.2.36 ListProperty

-

This type represents the data needed to define a ListProperty as mandated by clause 4.5.21. Note that in case of concise representation, the type can be omitted (see clause 4.5.21.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.36‑1.

-
-

Table 5.2.36-1: NGSI-LD ListProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “ListProperty” -
-1 -
-Node type. -
-valueList -
-An array of JSON values as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-1 -
-Ordered array of Property Values. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property list values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the ListProperty. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the ListProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the valueList attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
- -
-

Property

-

or Property[] (see note 1)

-
-See datatype definition in clauses 5.2.5 -
-0..N -
-Properties of the ListProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the ListProperty. -
-

LanguageProperty

-

or LanguageProperty[] (see note 1)

-
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the ListProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the ListProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the ListProperty. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the ListProperty. -
- -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the ListProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the ListProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.36-2) of the ListProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.36-2: Additional members of the NGSI-LD ListProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of ListProperties -
-0..1 -
-URI uniquely identifying a ListProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousValueList -
-An array of JSON values as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-0..1 -
-Ordered array of previous Property Values. -
-

5.2.37 ListRelationship

-

This type represents the data needed to define a ListRelationship as mandated by clause 4.5.22. Note that in case of concise representation, the type can be omitted (see clause 4.5.22.3) and the objectList may also be represented as an ordered array of Strings.

-

The supported JSON members shall follow the requirements provided in Table 5.2.37‑1.

-
-

Table 5.2.37-1: NGSI-LD ListRelationship data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “ListRelationship” -
-1 -
-Node type. -
-objectList -
-

JSON Object[] or

-

String[]

-
-

In the normalized form, each array element holds a JSON object containing a single Attribute with a key called“object”and where the value is a valid URI.

-

In the concise form, each string in the array holds a valid URI

-
-1 -
-Ordered array of Relationship target objects. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of relationship list objects. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the ListRelationship. See clause 4.22. -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the ListRelationship guaranteeing its integrity. -
-objectType -
-String or String[] -
-0..1 -
-

Node Type of the Relationship’s target object.

-

Both short hand string(s) (type name) or URI(s) are allowed.

-
-
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
- -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the ListRelationship. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the ListRelationship. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the ListRelationship. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the ListProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the ListRelationship. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the ListRelationship. -
- -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the ListRelationship. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the ListRelationship. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.37-2) of the ListRelationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.37-2: Additional members of the NGSI-LD ListRelationship data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-entityList -
-Entity[] -
-

See datatype definition in clause 5.2.4

-

Only used in Linked Entity Retrieval, if the join=inline option is explicitly requested

-
-0..1 -
-An array of inline Entities obtained by Linked Entity retrieval, corresponding to the ListRelationship’s target objects See clause 4.5.23.2. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of ListRelationships -
-0..1 -
-URI uniquely identifying a ListRelationship instance as mandated by clause 4.5.8. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousObjectList -
-

JSON Object[] or

-

String[]

-
-

In the normalized form, each array element holds a JSON object containing a containing a single Attribute with a key called“object”and where the value is a valid URI.

-

In the concise form, each string in the array holds a valid URI

-
-0..1 -
-Ordered array of previous Relationship target objects. -
-

5.2.38 JsonProperty

-

This type represents the data needed to define a JsonProperty as mandated by clause 4.5.24. In case of concise representation, the type can be omitted (see clause 4.5.24.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.38‑1.

-
-

Table 5.2.38-1: NGSI-LD JsonProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “JsonProperty” -
-1 -
-Node type. -
-json -
-JSON -
-1 -
-Raw unexpandable JSON which shall not be interpreted as JSON-LD using the supplied @context. -
-
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the JsonProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the JsonProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the json attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
- -
-

Property

-

or Property[] (see note 1)

-
-See datatype definitions in clauses 5.2.5 -
-0..N -
-Properties of the JsonProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the JsonProperty. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the JsonProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the JsonProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the JSONProperty. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the JsonProperty. -
- -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the JsonProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the JsonProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.38-2) of the JsonProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.38-2: Output only members of the NGSI-LD JsonProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime(clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of JsonProperties -
-0..1 -
-URI uniquely identifying a JsonProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousJson -
-JSON -
-Only used in Notifications -
-0..1 -
-Previous JsonProperty’s json. -
-

5.2.39 EntityMap

-

This type represents the data needed to define an EntityMap as mandated by clause 4.5.25.

-

The supported JSON members shall follow the requirements provided in Table 5.2.39‑1.

-
-

Table 5.2.39-1: NGSI-LD EntityMap data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-EntityMap ID. -
-type -
-String -
-It shall be equal to “EntityMap” -
-1 -
-Node type. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-1 -
-Expiration date for the EntityMap. -
-

The following output only members (defined by Table 5.2.39-2) of the EntityMap data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by ContextConsumers. In the event that they are provided in update operations NGSI-LD implementations shall ignore them.

-
-

Table 5.2.39-2: Additional members of the NGSI-LD EntityMap data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entityMap -
-JSON -
-

A set of key-value pairs whose keys shall be strings representing Entity ids and whose values shall be an array holding every CSourceRegistration id which is relevant to the ongoing Context Information Consumption request (see clause 4.21).

-

The key “@none” shall be used to refer to an Entity that is held locally.

-
-1 -
-System generated mapping of Entities to CSourceRegistrations. -
-linkedMaps -
-JSON -
-A set of key-value pairs whose keys shall be strings representing CSourceRegistration ids which are relevant to the ongoing Context Information request and whose values shall represent the associated EntityMap id used by the ContextSource. -
-1 -
-System generated mapping of Context CSourceRegistrations to a URI indicating which EntityMaps was used by the Context Source. -
-

5.2.40 Context Source Identity

-

This type represents the data uniquely identifying a Context Source, and if the Context Source supports multi-tenancy (see clause 4.14) uniquely identifying a Tenant within that Context Source.

-

The supported JSON members shall follow the requirements provided in Table 5.2.40‑1.

-
-

Table 5.2.40-1: Context Source Identity data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Context Source ID. -
-type -
-String -
-It shall be equal to “ContextSourceIdentity” -
-1 -
-JSON-LD @type. -
-contextSourceAlias -
-String -
-Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] -
-1 -
-

A unique id for a Context Source which can be used to identify loops.

-

In the multi-tenancy use case (see clause 4.14), this id shall be identifying a specific Tenant within a registered Context Source.

-
-contextSourceUptime -
-String -
-String representing a duration in ISO 8601 [17] format -
-1 -
-Total Duration that the Context Source has been available. -
-contextSourceTimeAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Current time observed at the Context Source. Timestamp See clause 4.8. -
-contextSourceExtras -
-JSON -
-0..1 -
-Instance specific information relevant to the configuration of the Context Source itself in raw un-expandable JSON which shall not be interpreted as JSON-LD using the supplied @context. -
-
-

5.2.41 Snapshot

-

This type represents the data needed to create and manage a Snapshot.

-

The supported JSON members shall follow the requirements provided in Table 5.2.41‑1.

-
-

Table 5.2.41-1: Snapshot data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-0..1 -
-System-generated at creation time, if it is not provided. It cannot be later modified in update operations. -
-type -
-String -
-It shall be equal to “Snapshot” -
-1 -
-JSON-LD @type. -
-snapshotQueries -
-Query[] -
-List of Query (clause 5.2.23), where no Query no “temporalQ” element. -
-0..1 -
-Allows clients to specify a list of queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of “snapshotQueries” or “snapshotTemporalQueries” shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status or cloning the Snapshot. -
-snapshotTemporalQueries -
-Query[] -
-List of Query (clause 5.2.23), where each Query has “temporalQ” element. -
-0..1 -
-Allows clients to specify a list of temporal queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of “snapshotQueries” or “snapshotTemporalQueries” shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status. -
-snapshotLifetime -
-String -
-String representing a duration in ISO 8601 [17] format -
-0..1 -
-Suggested duration for which the requester wants the Snapshot to exist with respect to the current point in time. The actual expiresAt time of the Snapshot shall be set by the NGSI-LD system, possibly overriding the requested duration. -
-snapshotPriority -
-Number -
-Positive Integer between 1 and 10 -
-0..1 -
-The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It can be used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. -
-endpoint -
-String -
-Dereferenceable URI -
-0..1 -
-URI to which notifications regarding changes in the status of the Snapshot are to be sent. The information contained in the receiverInfo member shall be considered. -
-receiverInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to the receiver. -
-
-

The following output only members (defined by Table 5.2.41-2) of the Snapshot data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Consumers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.41-2: Output only members of the Snapshot data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-snapshotStatus -
-String -
-

It shall be one of:

-

“preparing”,“success”,“partial”,

-

“failure”

-

or “empty”

-

The initial status shall be“preparing”.

-
-1 -
-Allows clients to check the status of the Snapshot. -
-snapshotQueriesDetails -
-ExecutionResultDetails[] -
-List ofExecutionResultDetails (clause 5.2.42) -
-0..1 -
-List with one result per Snapshot query execution, in the same order as Snapshot queries. -
-snapshotTemporalQueriesDetails -
-ExecutionResultDetails[] -
-List ofExecutionResultDetails (clause 5.2.42) -
-0..1 -
-List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-

Expiration time for the snapshot - it is possible to indirectly update the member by updating snapshotLifetime.

-

See clause 4.8.

-
-lastUsedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated timestamp identifying the point in time when the snapshot was most recently used. It is initialized at creation time. See clause 4.8. -
-

5.2.42 ExecutionResultDetails

-

This type represents the details of the result of execution a request, e.g. a Query.

-

The supported JSON members shall follow the requirements provided in Table 5.2.42‑1.

-
-

Table 5.2.42-1: ExecutionResultDetails data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-problemDetails -
-@JSON -
-ProblemDetails (see IETF RFC 7807 [10]) -
-0..1 -
-Provides more details regarding the result status, especially when reporting an error. -
-resultStatus -
-String -
-

It shall be one of:

-

“success”,

-

“failure”

-

or “empty”

-
-1 -
-Describes the status of the result. “failure”, if an error is reported, “success”in case of a non-empty result and “empty” otherwise. -
-

5.2.43 OrderingParams

-

This datatype represents the parameters that convey the definition used whilst ordering Entities.

-

The supported JSON members shall follow the requirements provided in Table 5.2.43‑1.

-
-

Table 5.2.43-1: OrderingParams data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-collation -
-String -
-An ICU collation (see IETF RFC 6067 [36]). -
-0..1 -
-The Entities returned in the payload shall be ordered according to the collation given. By default, it shall be ICU “root” collation order (“und-x-icu”). -
-coordinates -
-JSON Array -
-A JSON Array coherent with the geometry type as per IETF RFC 7946 [8]. -
-

0..1

-

It shall be one if orderBy uses order by distance

-
-Coordinates of a Geometry used when sorting by distance. -
-geometry -
-String -
-A valid GeoJSON [8] geometry type excepting GeometryCollection. -
-0..1 -
-The type of geometry whose coordinates are used when sorting by distance. By default, it shall be a “Point” geometry. -
-orderBy -
-String[] -
-Each String is an Entity member (“id”, “type”, “scope” or an Attribute name) appended with an optional sorting style (“asc”, “desc”, “dist-asc”, “dist-desc”)as per clause 4.23. -
-1 -
-When defined, the Entities returned in the payload shall be ordered according to members defined. -
-

5.2.44 AggregationParams

-

This datatype represents the parameters required for supporting aggregation methods in temporal requests.

-

The supported JSON members shall follow the requirements provided in Table 5.2.44‑1.

-
-

Table 5.2.44-1: AggregationParams data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-aggrMethods -
-Comma separated list of strings -
-Each String represents an aggregation method, as defined by clause 4.5.19. -
-1 -
-- -
-aggrPeriodDuration -
-String -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19.

-

If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-
-0..1 -
-- -
-

5.3 Notification data types

-

5.3.1 Notification

-

This datatype represents the parameters that allow building a notification to be sent to a subscriber. How to build this notification is detailed in clause 5.8.6.

-

The supported JSON members shall follow the indications provided in Table 5.3.1‑1.

-
-

Table 5.3.1-1: Notification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. -
-type -
-String -
-It shall be equal to “Notification” -
-1 -
-JSON-LD @type. -
-data -
-NGSI-LD Entity[] or FeatureCollection -
-1 -
-

The content of the notification as NGSI-LD Entities. See clause 5.2.4.

-

If the notification has been triggered from a Subscription that has the notification.

-

endpoint.accept field set to application/geo+jsonthen data is returned as a FeatureCollection. In this case, if the notification.endpoint.receiverInfocontains the key “Prefer” and it is set to the value “body=json”, then the FeatureCollection will not contain an @context field.

-

If endpoint.accept is not set or holds another value then Entity[] is returned.

-
-
-notifiedAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Timestamp corresponding to the instant when the notification was generated by the system. -
-subscriptionId -
-String -
-Valid URI -
-1 -
-Identifier of the subscription that originated the notification. -
-

5.3.2 CSourceNotification

-

This datatype represents the parameters that allow building a Context Source Notification to be sent to a subscriber. How to build this notification is detailed in clause 5.11.7.

-

The supported JSON members shall follow the indications provided in Table 5.3.2‑1.

-
-

Table 5.3.2-1: CSourceNotification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameData TypeRestrictionsCardinalityDescription

{TAL}

-

id

{TAL}

-

String

{TAL}

-

Valid URI

{TAL}

-

1

{TAL}

-

CSource notification identifier (JSON-LD @id).

{TAL}

-

type

{TAL}

-

String

{TAL}

-

It shall be equal to “ContextSourceNotification”

{TAL}

-

1

{TAL}

-

JSON-LD @type.

{TAL}

-

data

{TAL}

-

CSource

-

Registration[]

{TAL}

-

1

{TAL}

-

The content of the notification as NGSI-LD CSourceRegistrations. See clause 5.2.9.

{TAL}

-

notifiedAt

{TAL}

-

String

{TAL}

-

DateTime (see clause 4.6.3)

{TAL}

-

1

{TAL}

-

Timestamp corresponding to the instant when the notification was generated by the system.

{TAL}

-

subscriptionId

{TAL}

-

String

{TAL}

-

Valid URI

{TAL}

-

1

{TAL}

-

Identifier of the subscription that originated the notification.

{TAL}

-

triggerReason

{TAL}

-

String

{TAL}

-

TriggerReasonEnumeration (see clause 5.3.3)

{TAL}

-

1

{TAL}

-

Indicates whether the CSources in the CSourceRegistration(s) in data are newly matching (initial notification or creation), have been updated (but still match) or do not match any longer.

-

5.3.3 TriggerReasonEnumeration

-

The enumeration can take one of the following values:

-
- -
-

5.3.4 SnapshotNotification

-

This datatype represents the parameters that allow building a snapshot notification to be sent to a subscriber. How to build this notification is detailed in clause 5.16.6.

-

The supported JSON members shall follow the indications provided in Table 5.3.4‑1.

-
-

Table 5.3.4-1: SnapshotNotification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-Id -
-String -
-Valid URI -
-1 -
-Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. -
-type -
-String -
-It shall be equal to “SnapshotNotification” -
-1 -
-JSON-LD @type. -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Expiration time for the snapshot - if expiresAt is before notifiedAt, the notification indicates that the snapshot has been deleted. In this case, snapshotReady shall be set to false. -
-notifiedAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Timestamp corresponding to the instant when the notification was generated by the system. -
-snapshotId -
-String -
-Valid URI -
-1 -
-Identifier of the snapshot whose status change triggered the notification. -
-snapshotPriority -
-Number -
-Positive Integer between 1 and 10 -
-1 -
-The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It is used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. -
-snapshotQueriesDetails -
-ExecutionResultDetails[] -
-List ofExecutionResultDetails (clause 5.2.42) -
-0..1 -
-List with one result per Snapshot query execution, in the same order as Snapshot queries. -
-snapshotStatus -
-String -
-

It shall be one of:

-

“success”,“partial”,

-

“failure”

-

or “empty”

-
-1 -
-Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying. -
-temporalSnapshotQueriesDetails -
-ExecutionResultDetails[] -
-List ofExecutionResultDetails (clause 5.2.42) -
-0..1 -
-List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. -
-

5.4 NGSI-LD Fragments

-

When updating NGSI-LD elements (Entities, Attributes, Context Source Registrations or Subscriptions) it is necessary to have a means of describing a set of modifications to their content.

-

An NGSI-LD Fragment is a JSON Merge Patch document [16] and [i.10] which describes changes to be made to a target JSON-LD document using a syntax that closely mimics the document being modified.

-

An NGSI-LD Fragment is a JSON-LD Object which shall include the following members:

-
- -
-
-
-

EXAMPLE 1:

-
-
-

The following Subscription Fragment allows the modification of a Subscription by changing its endpoint’s URI:

-
{
-    "id": "urn:ngsi-ld:Subscription:MySubscription",
-"type": "Subscription",
-"endpoint": {
-    "uri": "http://example.org/newNotificationEndPoint"
-}
-}
-
-
-
- -
-
-
-

EXAMPLE 2:

-
-
-

The following NGSI-LD Fragment allows the modification of an Entity by changing its batteryLevel Attribute, updating the observedAt sub-Attribute, removing the providedBy sub-Attribute and removing the uncharged Attribute from the Entity:

-
{
-"id": "urn:ngsi-ld:TemperatureSensor:001",
-"type": "TemperatureSensor",
-"batteryLevel": {
-"type": "Property",
-"value": 7,
-"observedAt": "2022-03-14T12:51:02.000Z",
-"providedBy": "urn:ngsi-ld:null"
-},
-"uncharged" : {
-"type": "Property",
-"value": "urn:ngsi-ld:null"
-}
-}
-
-
-

5.5 Common Behaviours

-

5.5.1 Introduction

-

This clause defines common behaviours for the API operations.

-

When comparing URIs, implementations shall follow the recommendations of IETF RFC 3986 [5], section 6.

-

5.5.2 Error types

-

Table 5.5.2‑1 details a list of error types defined by NGSI-LD. The particular conditions under which error type shall be raised are defined when describing each operation supported by the API.

-
-

Table 5.5.2-1: Error types in NGSI-LD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Error Type -
-Description -
-https://uri.etsi.org/ngsi-ld/errors/AlreadyExists -
-The referred element already exists. -
-https://uri.etsi.org/ngsi-ld/errors/BadRequestData -
-The request includes input data which does not meet the requirements of the operation. -
-https://uri.etsi.org/ngsi-ld/errors/Conflict -
-The operation conflicts with the current state of the system. -
-https://uri.etsi.org/ngsi-ld/errors/InternalError -
-There has been an error during the operation execution. -
-https://uri.etsi.org/ngsi-ld/errors/InvalidRequest -
-The request associated to the operation is syntactically invalid or includes wrong content. -
-https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable -
-A remote JSON-LD @context referenced in a request cannot be retrieved by the NGSI-LD Broker and expansion or compaction cannot be performed. -
-https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport -
-The NGSI-LD API implementation does not support multiple tenants. -
-https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant -
-The addressed tenant does not exist. -
-https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported -
-The operation is not supported. -
-https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound -
-The referred resource has not been found. -
-https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery -
-The query associated to the operation is too complex and cannot be resolved. -
-https://uri.etsi.org/ngsi-ld/errors/TooManyResults -
-The query associated to the operation is producing so many results that can exhaust client or server resources. It should be made more restrictive. -
-

5.5.3 Error response payload body

-

When reporting errors back to clients, NGSI-LD implementations shall generate a JSON object in accordance with IETF RFC 7807 [10], section 3.1, including, at least the following terms:

-
- -
-

Even though IETF RFC 7807 [10] defines a specific MIME type for error payloads, NGSI-LD implementations shall use the standard JSON MIME type (“application/json”) when reporting errors, so that old clients or existing tools are not broken.

-
-
-

EXAMPLE:

-
-
-
{
-"type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound",
-"title": "Resource not found.",
-"detail": "urn:ngsi-ld:Device:widget001 was not found",
-"status": 404,
-"instance": "urn:ngsi-ld:Device:widget001"
-}
-
-
-

5.5.4 General NGSI-LD validation

-

All the operations that take a JSON-LD document as input shall process such JSON-LD document as follows:

-
- -
-

5.5.5 Default @context assignment

-

If the input provided by an API client does not include any @context, then the implementation shall at minimum assign the Core @context to such an input. In addition, the Context Broker implementation may allow configuring a default user @context (with default terms), to be used when no user @context is provided. The Core @context shall always take precedence.

-

5.5.6 Operation execution and generic error handling

-

When executing an operation if an unexpected error happens and the operation cannot be completed, implementations shall raise an error of type InternalError. This includes, as well, situations such as database timeouts, etc.

-

If the NGSI-LD endpoint is not capable of executing the requested operation, an error of type OperationNotSupported shall be raised. This may happen in a distributed architecture where a Context Broker might not be able to store Entities (only to forward queries to Context Sources), and as a result, certain operations such as “Create Entity” might not be supported.

-

When a query operation is so complex that cannot be resolved by an NGSI-LD system, implementations shall raise an error of type TooComplexQuery.

-

When a query operation is producing so many results that can potentially exhaust client or server resources, or it can be just impractical to be managed, implementations shall raise an error of type TooManyResults. The threshold conditions used as criteria to raise such error is up to each implementation.

-

When a remote JSON-LD @context referenced by an incoming request is not available, implementations shall raise an error of type LdContextNotAvailable. If the remote JSON-LD @context is invalid, implementations shall raise an error of type BadRequestData.

-

5.5.7 Term to URI expansion or compaction

-

NGSI-LD API operations allow clients to use short-hand strings as non-qualified names, particularly for Property, Relationship or Type names and VocabProperty values. For instance, an API client can refer to the term “Vehicle” as a non-qualified type name. When executing API update-related operations, NGSI-LD systems shall expand terms to URIs, in order to obtain and store Fully Qualified Names. Likewise, when executing query-related operations, NGSI-LD systems shall compact URIs (Fully Qualified Names) to short terms in order to provide short-hand strings to context consumers.

-

The term to URI expansion or compaction shall be performed using a @context as described by the JSON-LD specification [2], section 5.1, and in clause 4.4. In the absence of a user @context, the term expansion or compaction shall be performed according to clause 5.5.5.

-

For the avoidance of doubt, the @context used to perform compaction or expansion of terms shall be the one provided by each API call (or the default @context in its absence), and not any other @context which might have been supplied previously. For instance, when performing “Query Entity” operations (clause 5.7.2), the @context used to perform URI expansion and compaction shall be the one provided by the request.

-

In case of HTTP binding via GET (clause 6.4.3.2) of the “Query Entity” operation, this means using the JSON-LD Link Header as described by the JSON-LD specification [2], section 6.2. In case of HTTP binding via POST (clause 6.23.3.1), of the “Query Entity” operation, this means giving the @context either via Link Header or within the payload body, depending on the Content-Type Header being ”application/json” or ”application/ld+json”, respectively.

-

It is important to warn users that updating a @context could lead to behaviour that might be perceived as inconsistent. If, for instance, a fully qualified name that qualified a given short-hand name is changed, from that moment onwards, the short-hand name is referencing a different Attribute. This will effectively change the results of queries that use the given short name, possibly not giving back anymore the expected set of results.

-

Moreover, this user @context shall not:

-
- -
-

Parts of user @context that are not following the two points above should result in an error of type BadRequestData, because JSON-LD Scoped Contexts and nested embedded @context could be used to modify terms defined in the Core @context or to reshape NGSI-LD Elements during the expansion of terms.

-

As the Core @context is protected and cannot be overridden, when performing term to URI expansion or compaction, implementations shall always consider the Core @context as having absolute precedence, regardless of the position of the Core @context in the @context array of elements. Nonetheless, NGSI-LD data providers may use appropriate term prefixing to ensure that a proper term to URI expansion or compaction is performed.

-

At compaction time, in the event that no matching term is found in the current @context, implementations shall render Fully Qualified Names.

-
-
-

EXAMPLE:

-
-
-

An entity of type “Vehicle” bound to a certain @context , C, will match a query by “Vehicle” type if and only if the supplied query @context , Q, maps the term “Vehicle” to the same URI as C.

-
-
-
-

Note that the JsonProperty is designed to hold native JSON values which are by definition not available for expansion and compaction via an @context. Therefore, the given short-hand name is always used for accessing JSON keys within a JsonProperty json element.

-
-

5.5.8 Partial Update Patch Behaviour

-

The Partial Update Patch procedure modifies an existing NGSI-LD element by overwriting the data at the Attribute level, replacing it with the data provided in the NGSI-LD Fragment.

-

When updating NGSI-LD elements (Entities, Context Source Registrations or Context Subscriptions) using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element.

-

With respect to update operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [16]), in order to observe the name to URI expansion rules and the JSON-LD null processing):

-
- -
-
-
-

EXAMPLE 1:

-
-
-

Given an Entity containing the following Property:

-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 25,
-"unitCode":
-"CEL"
-"observedAt":
-"2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"type":
-"Property",
-"value": 100,
-"observedAt":
-"2022-03-14T13:00:00.000Z" 
-}
-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 100,
-"unitCode":
-"CEL"
-"observedAt":
-"2022-03-14T13:00:00.000Z"
-}
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

Given an Entity containing the following Property :

-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 25,
-"unitCode":
-"CEL"
-"observedAt":
-"2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 100,
-"observedAt":
-"2022-03-14T13:00:00.000Z"
-}
-}
-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 100,
-"observedAt":
-"2022-03-14T13:00:00.000Z"
-}
-}
-
-
-
-
-

EXAMPLE 3:

-
-
-

Given an Entity containing the following Property :

-
{
-"temperature":
-{
-"type":
-"Property",
-"value": 25,
-"unitCode":
-"CEL"
-"observedAt":
-"2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"temperature":
-{
-"type":
-"Property",
-"value":
-}
-}
-
-
-

5.5.9 Pagination Behaviour

-

5.5.9.1 General Pagination Behaviour

-

When resolving NGSI-LD Query operations, NGSI-LD Systems shall exhibit the behaviour described by the present clause:

-
- -
-

While iterating over a set of pages, there might be changes in the target result set, due to additions or removals of NGSI-LD Elements occurring in between. Implementations may detect those situations and may warn NGSI-LD Clients appropriately. During pagination, the same @context shall be used. An attempt to use a different @context should result in an BadRequestData error.

-

5.5.9.2 Pagination option using limit and offset

-

The general pagination behaviour described in clause 5.5.9.1 only requires pointers to the following and previous pages, which can be implemented in a completely opaque way. Pagination may also be implemented in a transparent way, giving the Context Consumer more control over the process. In this case, the parameters limit and offset should be used, allowing the Context Consumer to adapt the size of the page using limit and jump to a desired set of elements in the results using offset.

-

5.5.9.3 Pagination with Entity maps

-

In the case of queries based on Entity maps, the set of Entities considered for the result is fixed with the initial query creating the Entity map. However, the Entity information itself can be dynamic, so filters shall be rechecked before returning results. In the case of split Entities, the Entities in the Entity map can only be considered as candidate Entities, since, at the time of Entity map creation, the Entities have not been aggregated and thus the filters could not be applied. This can only be done when preparing a page for pagination. Thus, Entities not or no longer fitting the query shall be removed from the Entity map during pagination. Pages shall always be filled to the maximum, as long as Entities are available. When using the previous link, the set of Entities on the previous page may not be the same as before, due to dynamic changes resulting in Entities no longer fulfilling the filter criteria of the query. As a result, the first page when going backward, and the last page, when going forward, may have less than the maximum number of Entities.

-

5.5.10 Multi-Tenant Behaviour

-

If a Tenant is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specified Tenant. If no Tenant is specified, the operation shall apply to the implicitly existing default Tenant. If a Tenant is explicitly specified, but the system implementing the NGSI-LD API does not support multi-tenancy, an error of type NoMultiTenantSupport should be raised.

-

In case an operation applies to a Tenant, this information shall also be provided in the response to the operation. This also applies to notifications sent as a result of subscriptions (clauses 5.8 and 5.11).

-

A Tenant is represented in form of a String. How the Tenant is specified for an API operation is protocol binding specific. How Tenants are created, is implementation-specific.

-

One implementation option is to support the implicit creation of Tenants. This means that a Tenant is implicitly created when an NGSI-LD operation for creating information targets a new Tenant; this is the case for:

-
- -
-

All other NGSI-LD operations, e.g. for retrieving, updating, appending or deleting information that target a non-existing Tenant should raise an error of type NonexistentTenant.

-

If the system implementing the NGSI-LD API does not support multiple Tenants, the attempt to register a Context Source with Tenant information in the Context Source Registration should also result in an error of type NoMultiTenantSupport.

-

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

-

5.5.11.0 Foreword

-

The following operations operate on an array of entities (as input payload):

-
- -
-

It is allowed for such an input Entity array to contain more than one instance of the same entity (those instances have identical ids).

-

In order for such a request to be correctly handled, those instances that have the same id are processed by the Broker in the order they have in the array: the higher the index in the array, the later it will be processed. If the order is altered, the outcome may be altered.

-

All Entities and Attributes in the batch will get the same modifiedAt timestamp, so it makes sense to distinguish them via the observedAt temporal property.

-

Implementations shall treat the entity instances as if they had all arrived in separate requests.

-

The following clauses specify the behaviour in each case.

-

5.5.11.1 Batch Entity Creation case

-

The first occurrence of an entity in the input array (the oldest one) is used for the creation of the entity. Any subsequent instance of the same entity is reported as an error (entity already exists) in the response.

-

5.5.11.2 Batch Entity Creation or Update (Upsert) case

-

This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing entities, while the optional behaviour is to update already existing entities. Non existing entities are created in both modes.

-

If the entity does not yet exist, the first occurrence of an entity is used to create the entity, and subsequent instances of that same entity are used to either replace (default behaviour) or to update (optional behaviour) the entity. These replace or update operations shall be done in chronological order.

-

Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in clause 4.3.1). For TemporalEvolution of Entities (as defined in clause 4.3.1), all entity instances shall be taken into account, in the correct order.

-

5.5.11.3 Batch Entity Update case

-

This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing attributes of the entities, while the optional behaviour is to preserve already existing attributes of the entities.

-

Brokers shall send separate notifications for each individual update, taking throttling into account.

-

5.5.11.4 Batch Entity Delete case

-

The Batch Entity Delete operation has as input an array of Entity IDs, for the entities to be deleted. If an Entity ID is replicated in the array, the first occurrence will delete the entity, while subsequent occurrences of the same Entity ID will provoke an error in the response (entity does not exist).

-

5.5.11.5 Batch Entity Merge case

-

The Batch Entity Merge operation has as input an array of Entity IDs, for the entities to be merged. If an Entity ID is replicated in the array, these merge operations shall be done in chronological order. Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in clause 4.3.1). For TemporalEvolution of Entities (as defined in clause 4.3.1), all entity instances shall be taken into account, in the correct order.

-

5.5.12 Merge Patch Behaviour

-

The merge patch procedure modifies an existing NGSI-LD element by applying the set of changes found in an NGSI-LD Fragment data to the target resource. Unlike the partial update patch behaviour (described in clause 5.5.8), which replaces the complete element on the first level, e.g. a whole Attribute, the procedure described in this clause merges the provided information with the existing information up to an arbitrary depth, e.g. including going into JSON objects representing a Property value.

-

When merging NGSI-LD Entities using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element.

-

With respect to merge operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [16], in order to observe the name to URI expansion rules and JSON-LD null processing):

-
- -
-
-
-

EXAMPLE 1:

-
-
-

Given an Entity containing the following Property :

-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 25,
-    "unitCode": "CEL"
-    "observedAt": "2022-03-14T01:59:26.535Z"
-  }
-}
-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 100,
-    "observedAt": "2022-03-14T13:00:00.000Z"
-  }
-}
-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 100,
-    "unitCode": "CEL",
-    "observedAt": "2022-03-14T13:00:00.000Z"
-  }
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

Given an Entity containing the following Property :

-
{
-  "address": {
-    "type" : "Property",
-    "value" : {
-          "street": "Straße des 17. Juni",
-          "city": "Berlin",
-          "country": "Germany"
-    }
-  }
-}
-
{
-  "address": {
-    "type" : "Property",
-    "value" : {
-          "street": "Pariser Platz",
-          "country": "urn:ngsi-ld:null"
-    }
-  }
-}
-
{
-  "address": {
-    "type" : "Property",
-    "value": {
-          "street": "Pariser Platz",
-          "city": "Berlin"
-    }
-}
-
-
-

5.5.13 Limiting operations to local scope

-

The API provides a binding-specific mechanism to limit the execution of operations to a local scope, i.e. to only execute it based on information available in the Context Source or Context Brokerdirectly targeted by the request. This enables limiting cascading distributed operations (clause 4.3.6.4) and, in some cases, also enables broader local operations, e.g. pertaining to all entities, which would be too expensive in the distributed case.

-

The localOnlymember in the Subscription (clause 5.5.12) requests that the subscription only matches Entities stored locally.

-

The localOnly member in the RegistrationManagementInfo (clause 5.2.34) of a Context Source Registration request that, when contacting the registered ContextSource, a local scope shall be specified. Thus, the registered Context Source only provides its local information, not information from further Context Sources in its own Context Registry.

-

If the request limits the execution of the operation to the local scope, Context Source Registrations from the Context Registry will not be used.

-

Operations on a Snapshot (see clause 5.5.15) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations.

-

5.5.14 Distributed Transactional Behaviour

-

The following operations may occur as part of a distributed transactional request:

-
- -
-

In the case that a client wishes to indicate to a Context Broker that a request is part of a unitary sequence of requests, the Context Broker shall create and cache an EntityMap for future use and should return the location of said EntityMap in a specific field. The caching strategy and expiry time shall take into account a suggested expiry time, if present, and depend on implementation specific configurations. Context Sources should indicate that they do not support EntityMaps, through declining to return the location of an EntityMap when requested to do so.

-

If a subsequent request references an existent EntityMap, it shall be used for the purposes of Entity registration matching, and queries shall be filtered to only consider the Entities listed. Subsequent requests referencing an EntityMap shall use the same parameters as in the original request that created the EntityMap, except for the specification of Entity identifiers or parameters related to pagination, or, in the case of temporal requests, the temporal query. If an EntityMap has expired, or cannot be accessed, no inference can be made as to which entities are held within the Context Sources and a new one shall be created. An EntityMap fixes the Entities to be considered for subsequent requests based on it. The creating Context Source shall remove Entities from the EntityMap that do not match the filters of the query at the time of processing. Other components shall only be allowed to update the expiry timestamp of the EntityMap, which can optionally be extended if the Context Sources implementation allows for it.

-

5.5.15 Snapshot Behaviour

-

If a Snapshot (see clause4.3.7) is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specific Snapshot. Operations permitted on Snapshots are the same as those specified for the Core API and, if supported, the Temporal API (see Table4.3.5-1). This means all operations are implicitly limited to a local scope with all relaxations allowing broader operations (see clause5.5.13) and there is no need to explicitly set the local scope as a request parameter.The implicit limitation to local scope also means that Context Source Registrations from the Context Registry will not be used.

-

Snapshots are explicitly created, and the Snapshotidentifier is provided on creation. How the Snapshotidentifier is specified for an API operation is protocol binding specific.

-

The Snapshotconcept is orthogonal to the Tenant concept (see clause 4.14). Snapshots can also be created on Tenants. To execute an operation on a Snapshot created on a Tenant, both Snapshot and Tenant (see clause 5.5.10) have to be specified for an API operation.

-

If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be deleted, the snapshotPriority, ranging from 1 (minimum) to 10 (maximum) with 5 being the default priority, should be considered. An implementation may also consider other aspects like the expiresAt, or lastUsedAt timestamp for such a decision.

-

5.6 Context Information Provision

-

5.6.1 Create Entity

-

5.6.1.1 Description

-

This operation allows creating a new NGSI-LD Entity.

-

5.6.1.2 Use case diagram

-

A Context Producer can create an Entity within an NGSI-LD system as shown in Figure 5.6.1.2‑1.

-
-

-
-
-

Figure 5.6.1.2-1: Create entity use case

-
-

5.6.1.3 Input data

-

A JSON-LD document representing an NGSI-LD Entity as mandated by clause 5.2.4.

-

5.6.1.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
- -
- -
-
- -
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
- -
-

5.6.1.5 Output data

-

A URI identifying the newly created Entity.

-

5.6.2 Update Attributes

-

5.6.2.1 Description

-

This operation allows modifying an existing NGSI-LD Entity by updating already existing Attributes (Properties or Relationships) and by appending non-existing ones.

-

5.6.2.2 Use case diagram

-

A Context Producer can update Attributes within an NGSI-LD system as shown in Figure 5.6.2.2‑1.

-
-

-
-
-

Figure 5.6.2.2-1: Update Attributes use case

-
-

5.6.2.3 Input data

-
- -
-

5.6.2.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.2.5 Output data

-
- -
-

5.6.3 Append Attributes

-

5.6.3.1 Description

-

This operation allows modifying an NGSI-LD Entity by adding new attributes (Properties or Relationships).

-

5.6.3.2 Use case diagram

-

A Context Producer can append new Attributes to an existing Entity within an NGSI-LD system as shown in Figure 5.6.3.2-1.

-
-

-
-
-

Figure 5.6.3.2-1: Append Attributes use case

-
-

5.6.3.3 Input data

-
- -
-

5.6.3.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.3.5 Output data

-
- -
-

5.6.4 Partial Attribute update

-

5.6.4.1 Description

-

This operation allows performing a partial update on an NGSI-LD Entity’s Attribute (Property or Relationship). A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. This operation supports the deletion of sub-Attributes but not the deletion of the whole Attribute itself.

-

5.6.4.2 Use case diagram

-

A Context Producer can carry out a partial Attribute update of an Entity within an NGSI-LD System as shown in Figure 5.6.4.2-1.

-
-

-
-
-

Figure 5.6.4.2-1: Partial Attribute update use case

-
-

5.6.4.3 Input data

-
- -
-

5.6.4.4 Behaviour

-
- -
- -
- -
-
- -
-
-

then an error of type ResourceNotFound shall be raised.

-
-
- -
-

5.6.4.5 Output data

-

None.

-

5.6.5 Delete Attribute

-

5.6.5.1 Description

-

This operation allows deleting an NGSI-LD Attribute (Property or Relationship). The Attribute itself and all its children shall be deleted.

-

5.6.5.2 Use case diagram

-

A Context Producer can delete a specific Attribute within an NGSI-LD system as shown in Figure 5.6.5.2‑1.

-
-

-
-
-

Figure 5.6.5.2-1: Delete Attribute use case

-
-

5.6.5.3 Input data

-
- -
-

5.6.5.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-
- -
-

5.6.5.5 Output data

-

None.

-

5.6.6 Delete Entity

-

5.6.6.1 Description

-

This operation allows deleting an NGSI-LD Entity.

-

5.6.6.2 Use case diagram

-

A Context Producer can completely delete an Entity within an NGSI-LD system as shown in Figure 5.6.6.2‑1.

-
-

-
-
-

Figure 5.6.6.2-1: Delete Entity use case

-
-

5.6.6.3 Input data

-
- -
-

5.6.6.4 Behaviour

-
- -
-
- -
-
- -
-

5.6.6.5 Output data

-

None.

-

5.6.7 Batch Entity Creation

-

5.6.7.1 Description

-

This operation allows creating a batch of NGSI-LD Entities.

-

5.6.7.2 Use case diagram

-

A Context Producer can create a batch of NGSI-LD Entities within an NGSI-LD system as shown in Figure 5.6.7.2‑1.

-
-

-
-
-

Figure 5.6.7.2-1: Create a batch of Entities use case

-
-

5.6.7.3 Input data

-
- -
-

5.6.7.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.7.5 Output data

-
- -
-

5.6.8 Batch Entity Creation or Update (Upsert)

-

5.6.8.1 Description

-

This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed. In some database jargon this kind of operation is known as “upsert”.

-

5.6.8.2 Use case diagram

-

A Context Producer can create or update a batch of Entities within an NGSI-LD system as shown in Figure 5.6.8.2‑1.

-
-

-
-
-

Figure 5.6.8.2-1: Upsert a batch of Entities use case

-
-

5.6.8.3 Input data

-
- -
-
- -
-

5.6.8.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.8.5 Output data

-
- -
-

5.6.9 Batch Entity Update

-

5.6.9.1 Description

-

This operation allows updating a batch of NGSI-LD Entities.

-

5.6.9.2 Use case diagram

-

A Context Producer can update a batch of Entities within an NGSI-LD system as shown in Figure 5.6.9.2‑1.

-
-

-
-
-

Figure 5.6.9.2-1: Update a batch of Entities use case

-
-

5.6.9.3 Input data

-
- -
-

5.6.9.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.9.5 Output data

-
- -
-

5.6.10 Batch Entity Delete

-

5.6.10.1 Description

-

This operation allows deleting a batch of NGSI-LD Entities.

-

5.6.10.2 Use case diagram

-

A Context Producer can delete a batch of Entities within an NGSI-LD system as shown in Figure 5.6.10.2‑1.

-
-

-
-
-

Figure 5.6.10.2-1: Delete a batch of Entities use case

-
-

5.6.10.3 Input data

-
- -
-

5.6.10.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.10.5 Output data

-
- -
-

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

-

5.6.11.1 Description

-

This operation allows creating or updating (by adding new Attribute instances) the TemporalEvolutionof an Entity.

-

5.6.11.2 Use case diagram

-

A Context Producer can create the TemporalEvolutionof an Entity within an NGSI-LD system as shown in Figure 5.6.11.2-1.

-

Similarly, if the Entity already exists then an Update scenario will be in place.

-
-

-
-
-

Figure 5.6.11.2-1: Create or Update (Upsert) Temporal Evolution of an Entity use case

-
-

5.6.11.3 Input data

-

A JSON-LD document representing the TemporalEvolutionof an Entity as mandated by clause 5.2.20.

-

5.6.11.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
- -
- -
-
- -
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
- -
-

5.6.11.5 Output data

-

On creation, a URI identifying the newly created Temporal Evolution of an Entity. None otherwise.

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.12.1 Description

-

This operation allows modifying the TemporalEvolutionof an Entity by adding new Attribute instances.

-

5.6.12.2 Use case diagram

-

A Context Producer can add new Attributes or Attribute instances to an existing TemporalEvolutionof an Entity within an NGSI-LD system as shown in Figure 5.6.12.2‑1.

-
-

-
-
-

Figure 5.6.12.2-1: Add Attributes to Temporal Evolution of an Entity use case

-
-

5.6.12.3 Input data

-
- -
-

5.6.12.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
- -
-
- -
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
- -
-
- -
-
- -
-
- -
-

5.6.12.5 Output data

-

None.

-

5.6.13 Delete Attribute from Temporal Evolution of an Entity

-

5.6.13.1 Description

-

This operation allows deleting an Attribute (Property or Relationship) of the TemporalEvolutionof an Entity. The Attribute itself and all its child NGSI-LD elements shall be deleted.

-

5.6.13.2 Use case diagram

-

A Context Producer can delete a specific Attribute of the TemporalEvolutionof an Entity within an NGSI-LD system as shown in Figure 5.6.13.2‑1.

-
-

-
-
-

Figure 5.6.13.2-1: Delete Attribute from Temporal Evolution of an Entity use case

-
-

5.6.13.3 Input data

-
- -
-

5.6.13.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-
- -
-
- -
-
- -
-

5.6.13.5 Output data

-

None.

-

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity

-

5.6.14.1 Description

-

This operation allows modifying a specific Attribute (Property or Relationship) instance, identified by its instanceId, of the TemporalEvolutionof an Entity.

-

This operation enables the correction of wrong information that could have been previously added to the TemporalEvolutionof an Entity.

-

5.6.14.2 Use case diagram

-

A Context Producer can modify a specific Attribute instance, identified by a given instanceId, of the TemporalEvolutionof an Entitywithin an NGSI-LD system as shown in Figure 5.6.14.2‑1.

-
-

-
-
-

Figure 5.6.14.2-1: Modify Attribute Instance in Temporal Evolution of an Entity use case

-
-

5.6.14.3 Input data

-
- -
-

5.6.14.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-
- -
-
- -
-

5.6.14.5 Output data

-

None.

-

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity

-

5.6.15.1 Description

-

This operation allows deleting one Attribute instance (Property or Relationship), identified by its instanceId, of the TemporalEvolutionof an Entity. The Attribute itself and all its child elements shall be deleted. This operation enables the removal of individual Attribute instances that could have been previously added to the TemporalEvolutionof an Entity.

-

5.6.15.2 Use case diagram

-

A Context Producer can delete an Attribute instance, identified by a given instanceId, of the TemporalEvolutionof an Entity within an NGSI-LD system as shown in Figure 5.6.15.2‑1.

-
-

-
-
-

Figure 5.6.15.2-1: Delete Attribute Instance from Temporal Evolution of an Entity use case

-
-

5.6.15.3 Input data

-
- -
-

5.6.15.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-
- -
-
- -
-

5.6.15.5 Output data

-

None.

-

5.6.16 Delete Temporal Evolution of an Entity

-

5.6.16.1 Description

-

This operation allows deleting the TemporalEvolutionof an Entity.

-

5.6.16.2 Use case diagram

-

A Context Producer can completely delete the TemporalEvolutionof an Entity within an NGSI-LD system as shown in Figure 5.6.16.2‑1.

-
-

-
-
-

Figure 5.6.16.2-1: Delete Temporal Evolution of an Entity use case

-
-

5.6.16.3 Input data

-
- -
-

5.6.16.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-

5.6.16.5 Output data

-

None.

-

5.6.17 Merge Entity

-

5.6.17.1 Description

-

This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch processing rules defined in IETF RFC 7396 [16] by adding new Attributes (Properties or Relationships) or modifying or deleting existing Attributes associated with an existing Entity.

-

5.6.17.2 Use case diagram

-

A Context Producer can perform a merge on an Entity within an NGSI-LD system as shown in Figure 5.6.17.2‑1.

-
-

-
-
-

Figure 5.6.17.2-1: Merge Entity use case

-
-

5.6.17.3 Input data

-
- -
-

5.6.17.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
- -
-
- -
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
- -
-
-

Then, implementations shall perform a merge operation over the target Entity as mandated by clause 5.5.12, using the following procedure:

-
-
-

For each Attribute (Property or Relationship) included by the Entity Fragment:

-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.17.5 Output data

-
- -
-

5.6.18 Replace Entity

-

5.6.18.1 Description

-

This operation allows the modification of an existing NGSI-LD Entity by replacing all of the Attributes (Properties or Relationships).

-

5.6.18.2 Use case diagram

-

A Context Producer can replace an entire Entity within an NGSI-LD system as shown in Figure 5.6.18.2‑1.

-
-

-
-
-

Figure 5.6.18.2-1: Replace Entity use case

-
-

5.6.18.3 Input data

-
- -
-

5.6.18.4 Behaviour

-
- -
-
- -
-
- -
-

5.6.18.5 Output data

-

None.

-

5.6.19 Replace Attribute

-

5.6.19.1 Description

-

This operation allows the replacement of a single Attribute (Property or Relationship) within an NGSI-LD Entity.

-

5.6.19.2 Use case diagram

-

A Context Producer can carry out a replacement of an Attribute within an Entity within an NGSI-LD System as shown in Figure 5.6.19.2‑1.

-
-

-
-
-

Figure 5.6.19.2-1: Replace Attribute use case

-
-

5.6.19.3 Input data

-
- -
-

5.6.19.4 Behaviour

-
- -
-
- -
-
-

No further processing is required.

-
-
- -
-
- -
-
- -
-

5.6.19.5 Output data

-

None.

-

5.6.20 Batch Entity Merge

-

5.6.20.1 Description

-

This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch processing rules defined in IETF RFC 7396 [16] by adding new attributes (Properties or Relationships) or modifying or deleting existing attributes associated with an existing Entity.

-

5.6.20.2 Use case diagram

-

A Context Producer can merge a batch of Entities within an NGSI-LD system as shown in Figure 5.6.20.2‑1.

-
-

-
-
-

Figure 5.6.20.2-1: Merge a batch of Entities use case

-
-

5.6.20.3 Input data

-

A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by clause 5.2.4. See clause 5.5.11.5 for information on behaviour when there is more than one instance of the same entity in the input Array.

-

5.6.20.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.6.20.5 Output data

-
- -
-

5.6.21 Purge Entities

-

5.6.21.1 Description

-

This operation allows the deletion of entities within an NGSI-LD system based upon a query.

-

5.6.21.2 Use case diagram

-

A Context Producer can delete a set of entities which matches a specific query from an NGSI-LD system as shown in Figure 5.6.21.2‑1.

-
-

-
-
-

Figure 5.6.21.2-1: Purge Entities use case

-
-

5.6.21.3 Input data

-
- -
-

In the general case, it is not possible to purge a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.6.21.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
- -
-
- -
-
-

And thereafter:

-
-
- -
-
- -
-
- -
-

5.6.21.5 Output data

-

None.

-

5.7 Context Information Consumption

-

5.7.1 Retrieve Entity

-

5.7.1.1 Description

-

This operation allows retrieving an NGSI-LD Entity.

-

5.7.1.2 Use case diagram

-

A Context Consumer can retrieve a specific Entity from an NGSI-LD system as shown in Figure 5.7.1.2‑1.

-
-

-
-
-

Figure 5.7.1.2-1: Retrieve Entity use case

-
-

5.7.1.3 Input data

-
- -
-

5.7.1.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.7.1.5 Output data

-

A JSON-LD object representing the target Entity as mandated by clause 5.2.4 or a GeoJSON Feature as mandated by clause 5.2.29.

-

If a restrictive list of Entity member names is present, the Entity is reduced down to only contain the defined Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval).

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval).

-

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be compacted according to the supplied @context.

-

If a language filter is specified and any of the returned Attributes corresponds to a LanguageProperty, the LanguageProperty in question shall be converted into a Property. The value of this Property shall correspond to the value of the string or strings from the matching key-value pair of the languageMap where the key matches the language filter. A non-reified subproperty lang shall be included in the response indicating the chosen language.

-

If no match can be made for a LanguageProperty then a single language shall be chosen, up to the implementation.

-

If inline Linked Entity retrieval (see clause 4.5.23.2) is specified, and any of the returned Attributes corresponds to an annotated Relationship, then unless a URI has been previously encountered, an entity sub-Property shall be included in the response holding the Linked Entity data for each URI corresponding to that Relationship’s target object URI. If any of the returned Attributes corresponds to an annotated ListRelationship, then an entityList subproperty shall be included in the response holding the ordered array of Linked Entities corresponding to that ListRelationship’s target objectList URIs unless a URI has been previously encountered.

-

If flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, the response shall be an array of JSON-LD objects representing the target entity itself and the targets of its Relationships. If any of the returned Attributes corresponds to an annotated Relationship, unless a target URI has been previously encountered, thedata corresponding to each URI of the Relationship’s target object URIs is appended to the array. If any of the returned Attributes corresponds to an annotated ListRelationship, then an ordered array of additional Linked Entities is appended to the array which hold the data corresponding to each of the URIs found within ListRelationship’s target objectList unless a URI has been previously encountered.

-
-

Flattened Linked Entity retrieval output changes to a GeoJSON FeatureCollection as mandated by clause 5.2.30 if the Accept Header is set to “application/geo+json”.

-
-

If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response.

-

5.7.2 Query Entities

-

5.7.2.1 Description

-

This operation allows querying an NGSI-LD system.

-

5.7.2.2 Use case diagram

-

A Context Consumer can retrieve a set of entities which matches a specific query from an NGSI-LD system as shown in Figure 5.7.2.2‑1.

-
-

-
-
-

Figure 5.7.2.2-1: Query Entities use case

-
-

5.7.2.3 Input data

-
- -
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.7.2.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
- -
- -
-
- -
-
- -
-
- -
-
- -
-

5.7.2.5 Output data

-
-

A JSON-LD array representing the matching entities as defined by clause 5.2.4 or in the case of GeoJSON requests a FeatureCollection as mandated by clause 5.2.30. If Entity ordering is specified (see clause 4.23), then the JSON-LD array or FeatureCollection returned shall be ordered according to the list of member names specified. For each matching Entity, only the Attributes specified by the Attribute list parameter shall be included. If such parameter is not present, then all Attributes shall be included.

-
-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be compacted according to the supplied @context.

-

If a language filter is specified and any of the returned Attributes corresponds to a LanguageProperty, the LanguageProperty in question shall be converted into a Property. The value of this Property shall correspond to the value of the string or strings from matching key-value pair of the languageMap where the key matches the language filter. A non-reified subproperty langshall be included in the response indicating the chosen language.

-

If no match can be made for a LanguageProperty, then the default identified by the JSON-LD “@none” shall be chosen if present, otherwise the choice of a single language is up to the implementation.

-

If inline Linked Entity retrieval (see clause 4.5.23.2) is specified, and any of the returned Attributes corresponds to an annotated Relationship, then unless a URI has been previously encountered, an entity subproperty shall also be included in the response holding the data for each URI corresponding to that Relationship’s target object URIs. If any of the returned Attributes corresponds to an annotated ListRelationship, then an entityList subproperty shall also be included in the response holding the ordered data corresponding to that ListRelationship’s target objectList URIs, unless a URI has been previously encountered.

-

If flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, the response shall be an array of JSON-LD objects representing the matching entities and the targets of their Relationships. If any of the returned Attributes corresponds to an annotated Relationship, unless a URI has been previously encountered, then data for each URI corresponding to the Relationship’s target object URIs is appended to the array. If any of the returned Attributes corresponds to an annotated ListRelationship, then an array of additional Linked Entities is appended to the array which hold the data corresponding to each of the URIs found within ListRelationship’s target objectList unless a URI has been previously encountered.

-

If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response.

-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.3.1 Description

-

This operation allows retrieving the TemporalEvolution of an Entity.

-

5.7.3.2 Use case diagram

-

A Context Consumer can retrieve the TemporalEvolution of an Entity (in the form of a temporal representation) from an NGSI-LD system as shown in Figure 5.7.3.2‑1.

-
-

-
-
-

Figure 5.7.3.2-1: Retrieve Temporal Evolution of an Entity use case

-
-

5.7.3.3 Input data

-
- -
-

5.7.3.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.7.3.5 Output data

-

A JSON-LD object representing the TemporalEvolutionof the target Entity as mandated by clause 5.2.20.

-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

5.7.4 Query Temporal Evolution of Entities

-

5.7.4.1 Description

-

This operation allows querying the TemporalEvolution of Entities present in an NGSI-LD system. It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query.

-

5.7.4.2 Use case diagram

-

A Context Consumer can retrieve the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in Figure 5.7.4.2‑1.

-
-

-
-
-

Figure 5.7.4.2-1: Query Temporal Evolution of Entities use case

-
-

5.7.4.3 Input data

-
- -
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.7.4.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
- -

5.7.4.5 Output Data

-

A JSON-LD array representing the matching entities as defined by clause 5.2.21 and selected according to the behaviour described by clause 5.7.4.4.

-

If Entity ordering is specified (see clause 4.23), then the JSON-LD array returned shall be ordered according to the member names specified.

-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

5.7.5 Retrieve Available Entity Types

-

5.7.5.1 Description

-

This operation allows retrieving a list of NGSI-LD entity types for which entity instances exist within the NGSI-LD system.

-

5.7.5.2 Use case diagram

-

A Context Consumer can retrieve a list of NGSI-LD entity types from the system as shown in Figure 5.7.5.2‑1.

-
-

-
-
-

Figure 5.7.5.2-1: Retrieve Available Entity Types use case

-
-

5.7.5.3 Input data

-
- -
-

5.7.5.4 Behaviour

-
- -
-

5.7.5.5 Output data

-

A JSON-LD object representing the list of available entity types, as mandated by clause 5.2.24.

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.6.1 Description

-

This operation allows retrieving a list with a detailed representation of NGSI-LD entity types for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided @context) and the attribute names that existing instances of this entity type have.

-

5.7.6.2 Use case diagram

-

A Context Consumer can retrieve a list with a detailed representation of NGSI-LD entity types from the system as shown in Figure 5.7.6.2‑1.

-
-

-
-
-

Figure 5.7.6.2-1: Retrieve Details of Available Entity Types use case

-
-

5.7.6.3 Input data

-
- -
-

5.7.6.4 Behaviour

-
- -
-

5.7.6.5 Output data

-

A list of JSON-LD objects representing the details of available entity types as mandated by clause 5.2.25.

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.7.1 Description

-

This operation allows retrieving detailed entity type information about a specified NGSI-LD entity type for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided @context), the count of available entity instances and details about attributes that existing instances of this entity type have, including their name (as short name if available in the provided @context) and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty).

-

5.7.7.2 Use case diagram

-

A Context Consumer can retrieve a detailed representation of a specified NGSI-LD entity type from the system as shown in Figure 5.7.7.2‑1.

-
-

-
-
-

Figure 5.7.7.2-1: Retrieve Available Entity Type Information use case

-
-

5.7.7.3 Input data

-
- -
-

5.7.7.4 Behaviour

-
- -
-

5.7.7.5 Output data

-

A JSON-LD object representing the details of the specified entity type as mandated by clause 5.2.26.

-

5.7.8 Retrieve Available Attributes

-

5.7.8.1 Description

-

This operation allows retrieving a list of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system.

-

5.7.8.2 Use case diagram

-

A Context Consumer can retrieve a list of NGSI-LD attributes from the system as shown in Figure 5.7.8.2‑1.

-
-

-
-
-

Figure 5.7.8.2-1: Retrieve Available Attributes use case

-
-

5.7.8.3 Input data

-
- -
-

5.7.8.4 Behaviour

-
- -
-

5.7.8.5 Output data

-

A JSON-LD object representing the list of available attributes as mandated by clause 5.2.27.

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.9.1 Description

-

This operation allows retrieving a list with a detailed representation of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute.

-

5.7.9.2 Use case diagram

-

A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in Figure 5.7.9.2‑1.

-
-

-
-
-

Figure 5.7.9.2-1: Retrieve Details of Available Attributes use case

-
-

5.7.9.3 Input data

-

An optional JSON-LD context.

-

5.7.9.4 Behaviour

-

Return a list of JSON-LD objects representing the details of available attributes as mandated by clause 5.2.28 (restricted to the elements id, type, attributeName and typeNames) that belong to entity instances existing within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.

-

5.7.9.5 Output data

-

A list of JSON-LD objects representing the details of available attributes as mandated by clause 5.2.28 (restricted to the elements id, type, attributeName and typeNames).

-

5.7.10 Retrieve Available Attribute Information

-

5.7.10.1 Description

-

This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute, a count of available attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty).

-

5.7.10.2 Use case diagram

-

A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in Figure 5.7.10.2‑1.

-
-

-
-
-

Figure 5.7.10.2-1: Retrieve Available Attribute Information use case

-
-

5.7.10.3 Input data

-
- -
-

5.7.10.4 Behaviour

-

Return a JSON-LD object representing the details of available attributes as mandated by clause 5.2.28 that belong to entity instances existing within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.

-

5.7.10.5 Output data

-

A JSON-LD object representing the details of available attributes as mandated by clause 5.2.28.

- -

Retrieving information about available types or attributes can be an expensive operation depending on the scale and architectural design decisions of the NGSI-LD system. This is in particular the case for retrieving the information about all available entity types and attributes related to all entity information available in an NGSI-LD system. Especially in the case of distributed architecture (clause 4.3.3) and federated architecture (clause 4.3.4) checking all entities can be so expensive that it can become practically infeasible.

-

Therefore, implementations may only take into account only information that is available or can be derived from a local datastore and the Context Registry, when implementing the retrieval of available entity types and attributes, as described in clauses 5.7.5, 5.7.6, 5.7.7, 5.7.8, 5.7.9 and 5.7.10. Context registrations do not always reflect which entity instances are actually available from a Context Source at a particular point in time, but only which entity instances are possibly available from a Context Source, thus in this case the information about available entity types and attributes is to be interpreted as “possibly available”. Also, context registrations can have different granularities, i.e. they possibly only contain entity type or attribute information, and thus the provided information about available entity types and attributes is possibly incomplete as a result. In particular the attributeNames in the EntityType data structure (clause 5.2.25), the attributeDetails in the EntityTypeInfo data structure (clause 5.2.26), and the attributeTypes and typeNames in the Attribute data structure (clause 5.2.27) may be provided as empty arrays if the information is not included in the respective context registration. Implementations may also provide estimates for the entity count or attribute count instead of the accurate count.

-

As an alternative to relying on local information only, the request can be forwarded to all Context Sources which support the respective operation according to the Context Source Registration describing them. In this case the returned lists are merged with the local list of entity types before returning them. This approach is more expensive but leads to a more accurate result.

-

5.8 Context Information Subscription

-

5.8.1 Create Subscription

-

5.8.1.1 Description

-

This operation allows creating a new subscription.

-

5.8.1.2 Use case diagram

-

A Context Subscriber can create a subscription to receive context updates within an NGSI-LD system as shown in Figure 5.8.1.2‑1.

-
-

-
-
-

Figure 5.8.1.2-1: Create subscription use case

-
-

5.8.1.3 Input data

-
- -
-

5.8.1.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.8.1.5 Output data

-

A URI identifying the newly created Subscription.

-

5.8.2 Update Subscription

-

5.8.2.1 Description

-

This operation allows updating an existing subscription.

-

5.8.2.2 Use case diagram

-

A Context Subscriber can update an existing subscription within an NGSI-LD system as shown in Figure 5.8.2.2‑1.

-
-

-
-
-

Figure 5.8.2.2-1: Update subscription use case

-
-

5.8.2.3 Input data

-
- -
-

5.8.2.4 Behaviour

-
- -
-
- -
-

5.8.2.5 Output data

-

None.

-

5.8.3 Retrieve Subscription

-

5.8.3.1 Description

-

This operation allows retrieving an existing subscription.

-

5.8.3.2 Use case diagram

-

A Context Subscriber can retrieve a specific subscription from an NGSI-LD system as shown in Figure 5.8.3.2‑1.

-
-

-
-
-

Figure 5.8.3.2-1: Retrieve subscription use case

-
-

5.8.3.3 Input data

-

Id (URI) of the subscription to be retrieved (target subscription).

-

5.8.3.4 Behaviour

-
- -
-

5.8.3.5 Output data

-

A JSON-LD object representing the subscription details as mandated by clause 5.2.12.

-

5.8.4 Query Subscriptions

-

5.8.4.1 Description

-

This operation allows querying existing Subscriptions.

-

5.8.4.2 Use case diagram

-

A Context Consumer can query the existent Subscriptions from an NGSI-LD system as shown in Figure 5.8.4.2‑1.

-
-

-
-
-

Figure 5.8.4.2-1: Query subscriptions use case

-
-

5.8.4.3 Input data

-

A limit to the number of subscriptions to be retrieved. See clause 5.5.9.

-

5.8.4.4 Behaviour

-
- -
-

5.8.4.5 Output data

-

A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by clause 5.2.12.

-

5.8.5 Delete Subscription

-

5.8.5.1 Description

-

This operation allows deleting an existing subscription.

-

5.8.5.2 Use case diagram

-

A Context Subscriber can delete a subscription within an NGSI-LD system as shown in Figure 5.8.5.2‑1.

-
-

-
-
-

Figure 5.8.5.2-1: Delete subscription use case

-
-

5.8.5.3 Input data

-

A subscription identifier (URI).

-

5.8.5.4 Behaviour

-
- -
-
- -
-

5.8.5.5 Output data

-

None.

-

5.8.6 Notification behaviour

-

A notification is a message that allows a subscriber to be aware of the changes in subscribed Entities. Implementations shall exhibit the following behaviour:

-
- -
-
- -
-
- -
-
- -
-
- -
-
-

In all such cases, a JSON object with all the required information is provided, where the value or the object is set to the URI “urn:ngsi-ld:null” respectively or, in case of a LanguageProperty, the languageMap is set to {“@none”: “urn:ngsi-ld:null”}.

-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.9 Context Source Registration

-

5.9.1 Introduction

-

As described in clause 5.2.9, Context Source Registrations have a similar structure as Entities and are generally handled in the same way. However, there are some aspects that are specific to Registrations, in particular with respect to the handling of required properties. Thus, the operation descriptions for Registrations reference the respective operations for Entities and in addition specify any deviations and additions that are necessary for handling Context Source Registrations.

-

Context Source Registrations either contain information about Context Sources providing the latest information or about Context Sources providing temporal information, but not both. Context Sources that can provide both thus have to use two separate Context Source Registrations. If no temporal query is present, only Context Source Registrations for Context Sources providing latest information are returned, i.e. those which do not specify time intervals used for temporal queries. If a temporal query is present in a request for Context Source Registrations, only those Context Source Registrations that have a matching time interval are returned.

-

5.9.2 Register Context Source

-

5.9.2.1 Description

-

This operation allows registering a context source within an NGSI-LD system.

-

5.9.2.2 Use case diagram

-

A Context Provider can register one or more context sources within an NGSI-LD system as shown in Figure 5.9.2.2‑1.

-
-

-
-
-

Figure 5.9.2.2-1: Register context source use case

-
-

5.9.2.3 Input data

-

A data structure conforming to the CSourceRegistration data type as mandated by clause 5.2.9.

-

5.9.2.4 Behaviour

-

Implementations shall generally exhibit the behaviour described in clause 5.6.1.4, but instead of any type of entities only Context Source Registrations can be provided and the following exceptions shall apply:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.9.2.5 Output data

-

A URI identifying the newly created ContextSourceRegistration.

-

5.9.3 Update Context Source Registration

-

5.9.3.1 Description

-

This operation allows updating a Context Source Registration in an NGSI-LD system.

-

5.9.3.2 Use case diagram

-

A Context Provider can update a Context Source Registration in an NGSI-LD system as shown in Figure 5.9.3.2‑1.

-
-

-
-
-

Figure 5.9.3.2-1: Update context source registration use case

-
-

5.9.3.3 Input data

-
- -
-

5.9.3.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.9.3.5 Output data

-

None.

-

5.9.4 Delete Context Source Registration

-

5.9.4.1 Description

-

This operation allows deleting a Context Source Registration from an NGSI-LD system.

-

5.9.4.2 Use case diagram

-

A context provider can delete a context source registration from an NGSI-LD system as shown in Figure 5.9.4.2‑1.

-
-

-
-
-

Figure 5.9.4.2-1: Delete context source registration use case

-
-

5.9.4.3 Input data

-

Registration identifier (URI) of the context source registration to be deleted (target registration).

-

5.9.4.4 Behaviour

-
- -
-

5.9.4.5 Output data

-

None.

-

5.10 Context Source Discovery

-

5.10.1 Retrieve Context Source Registration

-

5.10.1.1 Description

-

This operation allows retrieving a specific context source registration from an NGSI-LD system.

-

5.10.1.2 Use case diagram

-

A context consumer or a context provider can retrieve a specific context source registration from an NGSI-LD system as shown in Figure 5.10.1.2‑1.

-
-

-
-
-

Figure 5.10.1.2-1: Retrieve context source registration use case

-
-

5.10.1.3 Input data

-

Context source registration identifier (id) of the context source registration to be retrieved (target registration).

-

5.10.1.4 Behaviour

-
- -
-

5.10.1.5 Output data

-

A JSON-LD object representing the target context source registration as mandated by clause 5.2.9.

-

5.10.2 Query Context Source Registrations

-

5.10.2.1 Description

-

This operation allows discovering context source registrations from an NGSI-LD system. The behaviour of the discovery of context source registrations differs significantly from the querying of entities as described in clause 5.7.2. The approach is that the client submits a query for entities as described in clause 5.7.2, but instead of receiving the Entity information, it receives a list of Context Source Registrations describing Context Sources that possibly have some of the requested Entity information. This means that the requested Entities and Attributes are matched against the ‘information’ property as described in clause 5.12.

-

If no temporal query is present, only Context Source Registrations for Context Sources providing latest information, i.e. without specified time intervals, are considered. If a temporal query is present only Context Source Registrations with matching time intervals, i.e. observationInterval or managementInterval, are considered.

-

5.10.2.2 Use case diagram

-

A Context Consumer can discover context source registrations that may be able to provide (part of) the context information specified in the query from an NGSI-LD system as shown in Figure 5.10.2.2‑1.

-
-

-
-
-

Figure 5.10.2.2-1: Discover context source registrations use case

-
-

5.10.2.3 Input data

-
- -
-
- -
-
- -
-

It is not possible to retrieve a set of context source registrations related to entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via lists of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery.

-

5.10.2.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names;
    2. -
-
-
-
    -
  1. NGSI-LD Query;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery.
    2. -
-
-
-

If none of them is provided, then an error of type BadRequestData shall be raised (too wide query). Attributes specified in NGSI-LD Query or NGSI-LD GeoQuery shall be used for matching RegistrationInfo elements in the same way as the attributes in the list of Attribute names.

-
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.10.2.5 Output data

-

A JSON-LD array of matching Context Source Registrations as defined by clause 5.2.9. Instead of the original Context Source Registration which may contain a lot of irrelevant information, implementations should return filtered Context Source Registrations, which only contain context source registration information relevant for the query, in particular only matching RegistrationInfo elements.

-

5.11 Context Source Registration Subscription

-

5.11.1 Introduction

-

Context Source Registration Subscriptions in general work like context information subscriptions; however, instead of resulting in notifications with context information, the notifications contain Context Source Registrations describing Context Sources that can potentially provide the requested context information. If no temporal query is present, only Context Source Registrations for Context Sources providing latest information, i.e. without such time intervals, are considered. If a temporal query is present only Context Source Registrations with matching time intervals, i.e. observationInterval or managementInterval, are considered.

-

5.11.2 Create Context Source Registration Subscription

-

5.11.2.1 Description

-

This operation allows creating a new Context Source Registration Subscription.

-

5.11.2.2 Use case diagram

-

A Context Source Subscriber can subscribe to a new Context Source Registration as shown in Figure 5.11.2.2‑1.

-
-

-
-
-

Figure 5.11.2.2-1: Subscribe Context Source Registration use case

-
-

5.11.2.3 Input data

-
- -
-

5.11.2.4 Behaviour

-
- -
-
- -
-
- -
-
- -
-
- -
-

5.11.2.5 Output data

-

A URI identifying the newly created Subscription.

-

5.11.3 Update Context Source Registration Subscription

-

5.11.3.1 Description

-

This operation allows updating an existing Context Source Registration Subscription.

-

5.11.3.2 Use case diagram

-

A context source subscriber can update a Context Source Registration Subscription as shown in Figure 5.11.3.2‑1.

-
-

-
-
-

Figure 5.11.3.2-1: Update Context Source Registration Subscription use case

-
-

5.11.3.3 Input data

-
- -
-

5.11.3.4 Behaviour

-
- -
-

5.11.3.5 Output data

-

None.

-

5.11.4 Retrieve Context Source Registration Subscription

-

5.11.4.1 Description

-

This operation allows retrieving an existing Context Source Registration Subscription.

-

5.11.4.2 Use case diagram

-

A Context Source subscriber can retrieve a specific Context Source Registration Subscription as shown in Figure 5.11.4.2-1.

-
-

-
-
-

Figure 5.11.4.2-1: Retrieve Context Source Registration Subscription use case

-
-

5.11.4.3 Input data

-

Id (URI) of the subscription to be retrieved (target subscription).

-

5.11.4.4 Behaviour

-
- -
-

5.11.4.5 Output data

-

A JSON-LD object representing the subscription details as mandated by clause 5.2.12.

-

5.11.5 Query Context Source Registration Subscriptions

-

5.11.5.1 Description

-

This operation allows querying existing Context Source Registration Subscriptions.

-

5.11.5.2 Use case diagram

-

A context source subscriber can query all existing Context Source Registration Subscriptions as shown in Figure 5.11.5.2-1.

-
-

-
-
-

Figure 5.11.5.2-1: Query Context Source Registration Subscriptions use case

-
-

5.11.5.3 Input data

-

A limit to the number of Context Source Registration Subscriptions to be retrieved. See clause 5.5.9.

-

5.11.5.4 Behaviour

-
- -
-

5.11.5.5 Output data

-

A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by clause 5.2.12.

-

5.11.6 Delete Context Source Registration Subscription

-

5.11.6.1 Description

-

This operation allows deleting an existing Context Source Registration Subscription.

-

5.11.6.2 Use case diagram

-

A context source subscriber can delete a Context Source Registration Subscription as shown in Figure 5.11.6.2‑1.

-
-

-
-
-

Figure 5.11.6.2-1: Delete Context Source Registration Subscriptions use case

-
-

5.11.6.3 Input data

-
- -
-

5.11.6.4 Behaviour

-
- -
-

5.11.6.5 Output data

-

None.

-

5.11.7 Notification behaviour

-

A Context Source Notification is a message that allows a subscriber to be aware of the changes in the set of Context Source Registrations describing Context Sources that can potentially provide the requested context information. Implementations shall exhibit the behaviour described in clause 5.8.6 with the following exceptions:

-
- -
-
- -
-
- -
-
- -
-
- -
-

5.12 Matching Context Source Registrations

-

When querying Context Source Registrations as described in clause 5.10.2 and subscribing to Context Source Registrations as described in clause 5.11.2, the Entities and/or Attributes specified in the request have to be matched against the set of Context Source Registrations, extracting the matching ones. This clause describes this matching.

-

The relevant specification information in the query for Context Source Registrations are the selector of Entity Types (if present), the list of Entity identifiers (if present), the id pattern (if present) and the list of Attribute names (if present). In the case of subscriptions to Context Source Registrations, it is the Entities as specified in the array of type EntitySelector in the Subscription, the watchedAttributes element of the Subscription and the attributes specified as part of the NotificationParams element of the Subscription. If the attributes in the NotificationParams element are empty or not present, the matching is done as if no attribute identifiers have been specified, otherwise the combination of the watchedAttributes and the attributes in the NotificationParams element are used as the specified attribute identifiers for the matching.

-

Even though the way relevant Entities are specified differs in queries and subscriptions, they consist of the same information, so for the purpose of this clause, the specification of Entity Types or Attributes refers to the relevant elements for matching, i.e. Entity Types, Entity identifiers, id pattern and Attribute names. A specification of Entity Types or Attributes shall contain at least one of:

-
-
    -
  1. selector of Entity Types; or
    2. -
  2. list of Attribute names.
    3. -
-
-

A specification of Entity Types or Attributes matches a Context Source Registration if at least one of the RegistrationInfo elements in the information element matches. An Entity specification matches a RegistrationInfo if the following conditions hold:

-
- -
-

An Entity specification consisting of selector of Entity Types, Entity identifiers and id pattern matches an EntityInfo element of the RegistrationInfo if the type selector matches the entity types in the EntityInfo element and one of the following conditions holds:

-
- -
-

Attribute names match the combination of Properties and Relationships if one of the following conditions hold:

-
- -
-

If the request that triggered the matching includes a datasetId parameter and the CSourceRegistration to be matched contains a datasetId element, the CSourceRegistration should only be considered matching, if both have at least one value in common. If only one of them specifies a datasetId, it is considered a match.

-

In the case of distributed operations (see clause 4.3.6.4), where a listing of all previously encountered Context Sourcesis supplied with the request, no registration shall match if the CSourceRegistration contextSourceAlias can be found within the listing of previously encountered Context Sources.

-

Note that distributed queries (see clause 4.3.6.7), can be supplied with an EntityMap (see clause 4.5.25) which lists all Entity ids successfully matched during a previous request. If the location of an EntityMap is passed into a subsequent request, the retrieved EntityMap shall be used in preference to the matching algorithm described above, provided that the EntityMap is valid and has not expired.

-

5.13 Storing, Managing and Serving @contexts

-

5.13.1 Introduction

-

Context Brokers optionally (see clause 4.3.5) offer the capability to store and serve @contexts to clients. The stored @contexts may be managed by clients directly, via the APIs specified in clause 5.13. Clients can store custom user @contexts at the Context Broker, effectively using the Context Broker as a @context server.

-

Moreover, in order to optimize performance, brokers may automatically store and use the stored copies of common @contexts as a local cache, downloading them just once, thus avoiding fetching them over and over again at each NGSI-LD request. In order for the broker to understand if a needed @context is already in the local storage or not, the broker uses the URL, where the @context is originally hosted, as an identifier for it in the local storage. Consequently, the broker has no ability to cache @contexts that arrive to it as embedded parts within the NGSI-LD documents, since they are not uniquely (and implicitly) identified by any URL; Context Brokers only cache @contexts that are referred to by means of explicit URLs (either in the HTTP Link header or as URLs in the payload body). Thus, the recommended best-practice, in order to exploit caching, is that clients do not embed their user @contexts into their NGSI-LD documents; instead clients should explicitly host their user @contexts at their premises, or use the broker’s capability to host user @contexts on their behalf.

-

When an external @context is stored, either explicitly upon a client’s request or implicitly downloaded for caching purposes, the Context Broker generates a unique local @context identifier. The original @context’s URL, if any, is stored alongside the generated local id. The local id is then used for subsequent managing operations on the specific @context, that are specified in clauses 5.13.2 to 5.13.5. Moreover, the broker tags the entry with the current timestamp, (createdAt) so that, subsequently, clients can check the timestamp before deciding whether to force a refresh of the stored copy of the @context. This is primarily intended as a means for clients to well-behave, thus avoiding triggering continuous refresh of a stored @context on the broker, for fear that it is not at the latest version.

-

Stored @contexts are flagged as one of three kinds: “Cached”, “Hosted”, “ImplicitlyCreated”:

-
- -
-

5.13.2 Add @context

-

5.13.2.1 Description

-

With this operation, a client can ask the broker to store the full content of a specific @context, by giving it to the broker.

-

5.13.2.2 Use case diagram

-

A client can add an @context to be stored within an NGSI-LD system as shown in Figure 5.13.2.2‑1.

-
-

-
-
-

Figure 5.13.2.2-1: Add @context use case

-
-

5.13.2.3 Input data

-

A JSON object that has a top-level field named @context, i.e. a JSON object representing a JSON-LD “local context”. As specified in the JSON-LD specification [2], all extra information located outside of the @context subtree in the referenced object shall be discarded.

-

5.13.2.4 Behaviour

-

A new entry is created in the local storage and a locally unique identifier (URI) is generated for it. The JSON object representing the client-supplied @context and the current UTC time are stored alongside the locally unique identifier. That identifier shall be given back as a result in the output data. The entry is flagged as being of kind “Hosted”.

-

The behaviour described in clause 5.5.4 about JSON and JSON-LD validation shall be applied in case of invalid @context.

-

5.13.2.5 Output data

-

A locally unique URI identifying the @context in the broker’s internal storage.

-

5.13.3 List @contexts

-

5.13.3.1 Description

-

With this operation a client can obtain a list of URLs that represent all of the @contexts stored in the local context store of the broker. Each URL can be used to download the corresponding @context, and, in case the @context’s kind is “Cached”, it shall be the original URL the broker downloaded the @context from.

-

In case a details flag is set to true, the client obtains a list of JSON objects, each representing information (metadata) about an @context currently stored by the broker. Each JSON object contains information about the @context’s original URL (if any), its local identifier in the broker’s storage, its kind (“Cached”, “Hosted” and “ImplicitlyCreated”), its creation timestamp, its expiry date, and additional optional information.

-

5.13.3.2 Use case diagram

-

A client can list all @contexts stored within an NGSI-LD system as shown in Figure 5.13.3.2‑1.

-
-

-
-
-

Figure 5.13.3.2-1: List @contexts use case

-
-

5.13.3.3 Input data

-
- -
-

5.13.3.4 Behaviour

-

The broker shall provide a URL or JSON object for each @context currently stored in the internal broker’s storage, that match the filter. If no filter is specified, all kinds are included.

-

5.13.3.5 Output data

-

A list of URLs, or a list of resulting JSON objects containing the following fields:

-
- -
-

5.13.4 Serve @context

-

5.13.4.1 Description

-

With this operation a client can obtain the full content of a specific @context (only for @contexts of kind “Hosted” or “ImplicitlyCreated”), which is currently stored in the broker’s internal storage, or its metadata (for all kinds of stored @contexts).

-

5.13.4.2 Use case diagram

-

A client can request the broker to serve a specific @context stored within the NGSI-LD system as shown in Figure 5.13.4.2-1.

-
-

-
-
-

Figure 5.13.4.2-1: Serve @context use case

-
-

5.13.4.3 Input data

-
- -
-

5.13.4.4 Behaviour

-
- -
-

5.13.4.5 Output data

-

The full content of the indicated @context (or its metadata as specified in clause 5.13.3.5), or ResourceNotFound/OperationNotSupported errors.

-

5.13.5 Delete and Reload @context

-

5.13.5.1 Description

-

With this operation, a client supplies a local identifier to the broker, indicating a stored @context, that the broker shall remove from its storage. For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from. If the entry in the local storage that corresponds to the identifier is itself an array of @contexts, this operation will not delete the children, i.e. the @contexts in the array, but just the entry.

-

5.13.5.2 Use case diagram

-

A client can request the broker to delete (and optionally reload) a specific @context stored within the NGSI-LD system as shown in Figure 5.13.5.2‑1.

-
-

-
-
-

Figure 5.13.5.2-1: Delete and Reload @context use case

-
-

5.13.5.3 Input data

-
- -
-

5.13.5.4 Behaviour

-
- -
-

5.13.5.5 Output data

-

None.

-

5.14 Context Source Entity Mapping

-

5.14.1 Retrieve EntityMap

-

5.14.1.1 Description

-

With this operation a client can obtain a cached EntityMap which is currently stored in the broker’s internal storage, or memory.

-

5.14.1.2 Use case diagram

-

A client can request the broker to retrieve a specific EntityMap within the NGSI-LD system as shown in Figure 5.14.1.2-1.

-
-

-
-
-

Figure 5.14.1.2-1: Retrieve EntityMap

-
-

5.14.1.3 Input data

-

EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap).

-

5.14.1.4 Behaviour

-
- -
-

5.14.1.5 Output data

-

A JSON-LD object representing the target EntityMap as mandated by clause 5.2.39.

-

5.14.2 Update EntityMap

-

5.14.2.1 Description

-

This operation allows performing a partial update on an NGSI-LD EntityMap. A partial update only changes the elements provided in the EntityMap Fragment, leaving the rest as they are.

-

5.14.2.2 Use case diagram

-

A client can request the broker to update an EntityMap which is currently stored in the broker’s internal storage as shown in Figure 5.14.2.2‑1.

-
-

-
-
-

Figure 5.14.2.2-1: Update EntityMap

-
-

5.14.2.3 Input data

-
- -
-

5.14.2.4 Behaviour

-
- -
-

5.14.2.5 Output data

-

None.

-

5.14.3 Delete EntityMap

-

5.14.3.1 Description

-

This operation allows deleting an NGSI-LD EntityMap.

-

5.14.3.2 Use case diagram

-

A client can request the broker to completely delete an EntityMap held within the NGSI-LD system as shown in Figure 5.14.3.2-1.

-
-

-
-
-

Figure 5.14.3.2-1: Delete EntityMap

-
-

5.14.3.3 Input data

-

EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap).

-

5.14.3.4 Behaviour

-
- -
-

5.14.3.5 Output data

-

None.

-

5.14.4 Create EntityMap for Query Entities

-

5.14.4.1 Description

-

This operation is very similar to the Query Entities operation in clause 5.7.2, except that it does not directly return Entities, but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through the included Entities.

-

5.14.4.2 Use case diagram

-

A Context Consumer can retrieve an Entity map with the Entities that match a specific query from an NGSI-LD system as shown in Figure 5.14.4.2‑1.

-
-

-
-
-

Figure 5.14.4.2-1: Query Entities for creating EntityMap use case

-
-

5.14.4.3 Input data

-
-

To simplify the operation, the same parameters as for the Query Entities operation (clause 5.7.2) are allowed, but some of these are irrelevant for creating an Entity map and thus shall be ignored.

-
-
- -
-
- -
-
- -
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the Entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.14.4.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
- -
- -
- -
-
- -
-
- -
-

5.14.4.5 Output data

-

The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself.

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.14.5.1 Description

-

This operation is very similar to the Query Temporal Evolution of Entities operation in clause 5.7.4, except that it does not directly return the Temporal Evolution of Entities but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through Temporal Evolution of the included Entities.

-

5.14.5.2 Use case diagram

-

A Context Consumer can retrieve an Entity map with the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in Figure 5.14.5.2‑1.

-
-

-
-
-

Figure 5.14.5.2-1: Query Temporal Evolution for creating EntityMap use case

-
-

5.14.5.3 Input data

-

To simplify the operation, the same parameters as for the Query Temporal Evolution of Entities operation (clause 5.7.4) are allowed, but some of these are irrelevant for creating an Entity map and thus will be ignored.

-
- -
-

5.14.5.4 Behaviour

-
- -
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

5.14.5.5 Output Data

-
-

The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself.

-
-

5.15 Context Source Identity Information

-

5.15.1 Retrieve Context Source Identity Information

-

5.15.1.1 Description

-

With this operation, a client can obtain Context Source identity information which uniquely defines the Context Source itself. In the multi-tenancy use case (see clause 4.14), a client can obtain identify information about a specific Tenant within a Context Source.

-

5.15.1.2 Use case diagram

-

A client can request the broker to retrieveidentity information about a specific Context Source within the NGSI-LD system as shown in Figure 5.15.1.2‑1.

-
-

-
-
-

Figure 5.15.1.2-1: Retrieve Context Source Identity Information

-
-

5.15.1.3 Input data

-

None.

-

5.15.1.4 Behaviour

-
- -
-

5.15.1.5 Output data

-

A JSON-LD object representing the identity of the Context Source as mandated by clause 5.2.40.

-

5.16 Snapshot Functionality

-

5.16.1 Create Snapshot

-

5.16.1.1 Description

-

This operation allows creating a new snapshot.

-

5.16.1.2 Use case diagram

-

A Context Consumer can create a new snapshot to have a more consistent basis for queries on the persisted Entity information as shown in Figure 5.16.1.2‑1.

-
-

-
-
-

Figure 5.16.1.2-1: Create Snapshot use case

-
-

5.16.1.3 Input data

-
- -
-

5.16.1.4 Behaviour

-
- -
-

5.16.1.5 Output data

-

A URI identifying the newly created Snapshot.

-

5.16.2 Clone Snapshot

-

5.16.2.1 Description

-

This operation allows cloning a snapshot stored in an NGSI-LD system.

-

5.16.2.2 Use case diagram

-

A Context Consumer can clone an existing snapshot stored in an NGSI-LD system as shown in Figure 5.16.2.2‑1.

-
-

-
-
-

Figure 5.16.2.2-1: Clone Snapshot use case

-
-

5.16.2.3 Input data

-
- -
-

5.16.2.4 Behaviour

-
- -
-

5.16.2.5 Output data

-

A URI identifying the newly created Snapshot.

-

5.16.3 Retrieve Snapshot Status

-

5.16.3.1 Description

-

This operation allows retrieving the status of a Snapshot stored in an NGSI-LD system.

-

5.16.3.2 Use case diagram

-

A Context Consumer can retrieve the status of a Snapshot from an NGSI-LD system as shown in Figure 5.16.3.2‑1.

-
-

-
-
-

Figure 5.16.3.2-1: Retrieve Snapshot Status use case

-
-

5.16.3.3 Input data

-

Snapshot Id (URI) of the Snapshot whose status is to be retrieved.

-

5.16.3.4 Behaviour

-
- -
-

5.16.3.5 Output data

-

A JSON-LD object representing the Snapshot status as mandated by clause 5.2.41.

-

5.16.4 Update Snapshot Status

-

5.16.4.1 Description

-

This operation allows updating an existing Snapshot.

-

5.16.4.2 Use case diagram

-

A Context Consumer can update an existing Snapshot within an NGSI-LD system as shown in Figure 5.16.4.2‑1.

-
-

-
-
-

Figure 5.16.4.2-1: Update Snapshot Status use case

-
-

5.16.4.3 Input data

-
- -
-

5.16.4.4 Behaviour

-
- -
-

5.16.4.5 Output data

-

A JSON-LD object representing the Snapshot status as mandated by clause 5.2.41.

-

5.16.5 Delete Snapshot

-

5.16.5.1 Description

-

This operation allows deleting an existing Snapshot.

-

5.16.5.2 Use case diagram

-

A Context Consumer can delete a Snapshot within an NGSI-LD system as shown in Figure 5.16.5.2‑1.

-
-

-
-
-

Figure 5.16.5.2-1: Delete Snapshot use case

-
-

5.16.5.3 Input data

-
- -
-

5.16.5.4 Behaviour

-
- -
-

5.16.5.5 Output data

-

None.

-

5.16.6 Snapshot status notification behaviour

-

A Snapshot status notification allows the subscriber, typically the creator of the Snapshot, to be notified when the Snapshot is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour:

-
- -
-

5.16.7 Purge Snapshots

-

5.16.7.1 Description

-

This operation allows purging selected Snapshots.

-

5.16.7.2 Use case diagram

-

A Context Consumer can purge Snapshots within an NGSI-LD system as shown in Figure 5.16.7.2‑1.

-
-

-
-
-

Figure 5.16.7.2-1: Purge Snapshots use case

-
-

5.16.7.3 Input data

-
- -
-

5.16.7.4 Behaviour

-
- -
-

5.16.7.5 Output data

-

None.

- - diff --git a/API-html/11-tabapi-http-binding.html b/API-html/11-tabapi-http-binding.html deleted file mode 100644 index 3f2fb3a78e368f82f85e08a9be9545c195a2a029..0000000000000000000000000000000000000000 --- a/API-html/11-tabapi-http-binding.html +++ /dev/null @@ -1,14286 +0,0 @@ - - - - - - - -6 API HTTP Binding - - - - - - - - -

6 API HTTP Binding

-

6.1 Introduction

-

This clause defines the resources and operations of the NGSI-LD API. The NGSI-LD API is structured in terms of HTTP [3], [4] verbs, request and response payload bodies.

-

A non-normative OAS specification [i.12] of the referred HTTP binding can be found at [i.14].

-

6.2 Global Definitions and Resource Structure

-

All resource URIs of this API shall have the following root:

-
- -
-
-
-

NOTE 1:

-
-
-

The apiRoot discovery process is out of the scope of the present document.

-
-
-
-
-

NOTE 2:

-
-
-

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different, e.g. the Context Source related aspects can be implemented by a Context Registry as shown for the distributed and federated architectures (see clause 4.3 ), whereas the Entity-related aspects would be implemented by a Context Broker .

-
-
-
-
-

NOTE 3:

-
-
-

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different than the apiRoot for temporal aspects, e.g. the temporal aspects can be implemented by an NGSI-LD subsystem specialized in historical data.

-
-
-

The apiRoot includes the scheme (“http” or “https”), host and optional port, and an optional prefix string. The API shall support HTTP over TLS (also known as HTTPS - see IETF RFC 2818 [18]). TLS version 1.2 as defined by IETF RFC 5246 [19] shall be supported. HTTP without TLS is not recommended.

-

The apiName shall be set to “ngsi-ld” and the apiVersion shall be set to “v1” for the present document.

-

All resource URIs are defined relative to the above root URI. The structure of the resources under the root URI is shown in Figure 6.2‑1 and methods defined on them are shown in Table 6.2‑1.

-

An OpenAPI companion specification is available, see [37].

-
-

-
-
-

Figure 6.2-1: Resource URI structure of the NGSI-LD API

-
-
-

Table 6.2-1: Resources and HTTP methods defined on them

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Resource Name -
-Resource URI -
-HTTP Method -
-Meaning -
-Clauses -
-Entity List -
-/entities/ -
-POST -
-Entity creation -
-5.6.1; 6.4.3.1 -
-GET -
-Query entities -
-5.7.2; 6.4.3.2 -
-DELETE -
-Purge entities -
-5.6.21; 6.4.3.3 -
-Entity by id -
-/entities/{entityId} -
-GET -
-Entity retrieval by id -
-5.7.1; 6.5.3.1 -
-DELETE -
-Entity deletion by id -
-5.6.6; 6.5.3.2 -
-PATCH -
-Entity merge by id -
-5.6.17; 6.5.3.4 -
-PUT -
-Entity replacement by id -
-5.6.18; 6.5.3.3 -
-Attribute List -
-/entities/{entityId}/attrs/ -
-POST -
-Append Attributes to Entity -
-5.6.3; 6.6.3.1 -
-PATCH -
-Update Attributes of an Entity -
-5.6.2; 6.6.3.2 -
-Attribute by id -
-/entities/{entityId}/attrs/{attrId} -
-PATCH -
-Partial Attribute update -
-5.6.4; 6.7.3.1 -
-DELETE -
-Attribute deletion -
-5.6.5; 6.7.3.2 -
-PUT -
-Attribute replacement -
-5.6.19; 6.7.3.3 -
-Subscriptions List -
-/subscriptions/ -
-POST -
-Create Subscription -
-5.8.1; 6.10.3.1 -
-GET -
-Retrieve list of Subscriptions -
-5.8.4; 6.10.3.2 -
-Subscription by Id -
-/subscriptions/{subscriptionId} -
-GET -
-Subscription retrieval by id -
-5.8.3; 6.11.3.1 -
-PATCH -
-Subscription update by id -
-5.8.2; 6.11.3.2 -
-DELETE -
-Subscription deletion by id -
-5.8.5; 6.11.3.3 -
-Entity Types -
-/types/ -
-GET -
-Retrieve available entity types -
-5.7.5 and 5.7.6; 6.25.3.1 -
-Entity Type -
-/types/{type} -
-GET -
-Details about available entity type -
-5.7.7; 6.26.3.1 -
-Attributes -
-/attributes/ -
-GET -
-Available attributes -
-5.7.8 and 5.7.9; 6.27.3.1 -
-Attribute -
-/attributes/{attrId} -
-GET -
-Details about available attribute -
-5.7.10; 6.28.3.1 -
-Context source registration list -
-/csourceRegistrations/ -
-POST -
-Csource registration creation -
-5.9.2; 6.8.3.1 -
-GET -
-Discover Csource registrations -
-5.10.2; 6.8.3.2 -
-Context source registration by Id -
-/csourceRegistrations/{registrationId} -
-GET -
-Csource registration retrieval by id -
-5.10.1; 6.9.3.1 -
-PATCH -
-Csource registration update by id -
-5.9.3; 6.9.3.2 -
-DELETE -
-Csource registration deletion by id -
-5.9.4; 6.9.3.3 -
-Context source registration subscription list -
-/csourceSubscriptions/ -
-POST -
-Create subscription to Csource registration -
-5.11.2; 6.12.3.1 -
-GET -
-Retrieval of list of subscription to Csource registration -
-5.11.5; 6.12.3.2 -
-Context source registration subscription by Id -
-/csourceSubscriptions/{subscriptionId} -
-GET -
-Csource registration subscription retrieval by id -
-5.11.4; 6.13.3.1 -
-PATCH -
-Csource registration subscription update by id -
-5.11.3; 6.13.3.2 -
-DELETE -
-Csource registration subscription deletion by id -
-5.11.6; 6.13.3.3 -
-Entity Operations. Create -
-/entityOperations/create -
-POST -
-Batch Entity creation -
-5.6.7; 6.14.3.1 -
-Entity Operations. Upsert -
-/entityOperations/upsert -
-POST -
-Batch Entity creation or update (upsert) -
-5.6.8; 6.15.3.1 -
-Entity Operations. Update -
-/entityOperations/update -
-POST -
-Batch Entity update -
-5.6.9; 6.16.3.1 -
-Entity Operations. Delete -
-/entityOperations/delete -
-POST -
-Batch Entity deletion -
-5.6.10; 6.17.3.1 -
-Entity Operations. Query -
-/entityOperations/query -
-POST -
-Query entities based on POST -
-5.7.2; 6.23.3.1 -
-

Entity Operations.

-

Merge

-
-/entityOperations/merge -
-POST -
-Batch Entity merge -
-5.6.20; 6.31.3.1 -
-Temporal Evolution of Entities -
-/temporal/entities/ -
-POST -
-Temporal Evolution of an Entity creation -
-5.6.11; 6.18.3.1 -
-GET -
-Query Temporal Evolution of Entities -
-5.7.4; 6.18.3.2 -
-Temporal Evolution of an Entity by id -
-/temporal/entities/{entityId} -
-GET -
-Temporal Evolution of an Entity retrieval by id -
-5.7.3; 6.19.3.1 -
-DELETE -
-Temporal Evolution of an Entity deletion by id -
-5.6.16; 6.18.3.2 -
-Temporal Representation of Attribute List -
-/temporal/entities/{entityId}/attrs/ -
-POST -
-Temporal Evolution of Attribute of an Entity instance addition -
-5.6.12; 6.20.3.1 -
-Temporal Representation of Attribute by id -
-/temporal/entities/{entityId}/attrs/{attrId} -
-DELETE -
-Attribute from Temporal Evolution of an Entity deletion -
-5.6.13; 6.21.3.1 -
-Temporal Representation of Attribute Instance by id -
-/temporal/entities/{entityId}/attrs/{attrId} /{instanceId} -
-PATCH -
-Attribute Instance from Temporal Evolution of an Entity update by instance id -
-5.6.14; 6.22.3.1 -
-DELETE -
-Attribute Instance from Temporal Evolution of an Entity deletion by instance id -
-5.6.15; 6.22.3.2 -
-Create EntityMap for Query Temporal Evolution of Entities -
-/temporal/entityMaps/ -
-GET -
-Query temporal evolution of entities for creating entity map -
-

5.15.4;

-

6.35.3.1

-
-POST -
-Query temporal evolution of entities for creating entity map based on POST -
-

5.15.4;

-

6.35.3.2

-
-Temporal Query Operation -
-/temporal/entityOperations/query -
-POST -
-Query Temporal Evolution of Entities based on POST -
-5.7.4; 6.24.3.1 -
-Add and List @context -
-/jsonldContexts -
-POST -
-Add a user @context to the internal cache -
-5.13.2; 6.29.3.1 -
-GET -
-List all cached @contexts -
-5.13.3; 6.29.3.2 -
-Serve, Delete and Reload @context -
-/jsonldContexts/{contextId} -
-GET -
-Serve one specific user @context -
-5.13.4; 6.30.3.1 -
-DELETE -
-Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it -
-5.13.5; 6.30.3.2 -
-Create EntityMap for Query Entities -
-/entityMaps/ -
-GET -
-Query entities for creating entity map -
-

5.14.4;

-

6.34.3.1

-
-POST -
-Query entities for creating entity map based on POST -
-

5.14.4;

-

6.34.3.2

-
-Retrieve, Update and Delete Entity Maps -
-/entityMaps/{entityMapId} -
-GET -
-EntityMap Retrieval by id -
-5.14.1; 6.32.3.1 -
-PATCH -
-EntityMap Update by id -
-5.14.2; 6.32.3.2 -
-DELETE -
-EntityMap Deletion by id -
-5.14.3; 6.32.3.3 -
-Retrieve Context Source Identity Information -
-/info/sourceIdentity -
-GET -
-Context Source Identity Retrieval -
-5.15.1; 6.33.3.1 -
-Create Snapshot or Purge Snapshots -
-/snapshots/ -
-POST -
-Create Snapshot -
-

5.16.1;

-

6.36.3.1

-
-DELETE -
-Purge Snapshots -
-

5.16.7;

-

6.36.3.2

-
-Retrieve and Update Snapshot Status or Delete Snapshot -
-/snapshots/{snapshotId} -
-GET -
-Retrieve Snapshot Status -
-

5.16.3;

-

6.37.3.1

-
-PATCH -
-Update Snapshot Status -
-

5.16.4;

-

6.37.3.2

-
-DELETE -
-Delete Snapshot -
-

5.16.5;

-

6.37.3.3

-
-Clone Snapshot -
-/snapshots/{snapshotId}/clone -
-POST -
-Clone Snapshot -
-

5.16.2;

-

6.38.3.1

-
-

6.3 Common Behaviours

-

6.3.1 Introduction

-

This clause extends the API common behaviours to the particularities of the HTTP REST binding. For each operation implementations shall exhibit the common behaviours as specified by clause 5.5 and the behaviours defined by the present clause.

-

6.3.2 Error Types

-

This clause associates API error types (which shall be contained in the response payload body) defined by clause 5.5.2 with HTTP status codes as shown in Table 6.3.2‑1.

-
-

Table 6.3.2-1: Mapping of error types to HTTP status codes

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Error Type -
-HTTP status -
-https://uri.etsi.org/ngsi-ld/errors/AlreadyExists -
-

409

-
-https://uri.etsi.org/ngsi-ld/errors/BadRequestData -
-

400

-
-https://uri.etsi.org/ngsi-ld/errors/InternalError -
-

500

-
-https://uri.etsi.org/ngsi-ld/errors/InvalidRequest -
-

400

-
-https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable -
-

504

-
-https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport -
-

501

-
-https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant -
-

404

-
-https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported -
-

422

-
-https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound -
-

404

-
-https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery -
-

403

-
-https://uri.etsi.org/ngsi-ld/errors/TooManyResults -
-

403

-
-

In addition, implementations shall support the standard specific errors of HTTP bindings, such as the following:

-
- -
-

6.3.3 Reporting errors

-

When an API operation results in an error, implementations shall return an HTTP response as follows:

-
- -
-

6.3.4 HTTP request preconditions

-

For HTTP POST, PATCH and PUT HTTP requests implementations shall check the following preconditions:

-
- -
-

For HTTP PATCH requests “application/merge-patch+json” is allowed as Content-Type, as mandated by IETF RFC 7396 [16]. Implementations shall interpret such MIME type as equivalent to “application/json”.

-

For HTTP GET requests and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall check the following preconditions:

-
- -
-
- -
-

The order of the list above is significant. If the Accept header can be expanded to more than one of the options of the list, the first one of the list shall be selected, unless amended by the HTTP Accept header processing rules, e.g. the presence of a “q” parameter indicating a relative weight, (as mandated by IETF RFC 7231 [3], section 5.3.2) require otherwise.

-

If the Accept header is not present, “application/json” shall be assumed.

-

If an incoming HTTP request does not meet the preconditions stated above, an HTTP error response of type InvalidRequest shall be returned, with the following exceptions:

-
- -
-

Notwithstanding the above, if the Accept Header is set to “application/geo+json”:

-
- -
-

6.3.5 JSON-LD @context resolution

-

In the HTTP REST binding, implementations shall resolve the JSON-LD @*context* associated to an incoming HTTP request as follows:

-
- -
-
-
-

EXAMPLE:

-
-
-

The structure of the referred Link header is shown below. The first component (between < > ) is a dereferenceable URI pointing to the JSON-LD document which contains the @context to be used to expand the terms used by the corresponding operation. The second parameter is a fixed, non-dereferenceable URI used to denote a unique identifier and semantics for this header (marking it as a link to a JSON-LD @context ). The third and final parameter flags the MIME type of the linked resource (JSON-LD).

-
-
-
- -
-

In summary, from a developer’s perspective, for POST, PATCH and PUT operations, if MIME type is “application/ld+json”, then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is “application/json”, then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

-

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

-

6.3.6 HTTP response common requirements

-

Implementations shall honour the Accept header provided by HTTP requests as mandated by clause 6.3.4:

-
- -
-
- -
-
- -
-
- -
-
- -
-

Operations where the response payload body is not present such as successful HTTP POST, PATCH, PUT or DELETE operations and all error responses, do not include the Link header in the response.

-

Operations that result in an error that return a payload or that result in a partial success (207 Multi-Status) shall always respond with MIME type “application/json”, regardless of the Accept header. It is assumed that if a client application understands any of the supported MIME types, the application shall understand “application/json” errors. Only Fully Qualified Names shall be used in the payload body of error or partial success responses, as there is no context present.

-

No Content-Length HTTP header shall be present if the response code is 204.

-

6.3.7 Representation of Entities

-

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), Context Broker implementations shall support the parameter specified in Table 6.3.7‑1, which specifies all possible supported representations formats.

-

In contrast, at a minimum, registered Context Source implementations shall support the normalized representation of Entities as default. When a registered Context Source is unable to support additional representations, a 501 Not Implemented Error shall be raised.

-
-

Table 6.3.7-1: Entity representations: format + options parameter

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

When its value is “normalized”, a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2.

-

When its value is “concise”, a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members.

-

When its value is “simplified” (or its synonym “keyValues”). a simplified representation of Entities shall be provided as defined by clause 4.5.4.

-

If the Accept Header is set to “application/geo+json” the response will be in simplified GeoJSON format as defined by clause 4.5.17.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword “normalized”, a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2.

-

When its value includes the keyword “concise”, a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members.

-

When its value includes the keyword “simplified” (or its synonym “keyValues”). a simplified representation of Entities shall be provided as defined by clause 4.5.4.

-

If the Accept Header is set to “application/geo+json” the response will be in simplified GeoJSON format as defined by clause 4.5.17.

-
-

6.3.8 Notification behaviour

-

In the HTTP binding a notification that is triggered by a subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the subscription structure (defined by clauses 5.2.12, 5.2.14 and 5.2.15). For the HTTP binding, the protocol part of the endpoint URI is http or https. In case the optional MQTT notification binding (clause 7) is supported, the protocol part of the endpoint URI can also be mqtt or mqtts. The MIME type associated to the POST request shall be “application/json” by default. However, this can be changed to “application/ld+json”, or “application/geo+json” by means of the endpoint.accept member.

-

If the target MIME type is “application/json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP header for each member named “key” of the key, value pairs that make up the array shall be generated and included in the HTTP POST’s list of headers. The content of each custom header shall be set equal to the content of the corresponding “value” member of the KeyValuePair. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

If the target MIME type is “application/geo+json” and the notification.endpoint.receiverInfo member contains a key “Prefer”whose value is set to “body=json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the target MIME type is “application/geo+json” and the notification.endpoint.receiverInfo contains a key “Prefer” whose value is set to “body=ld+json” or the “Prefer” key is omitted or notification.endpoint.receiverInfo does not exist, then the HTTP notification request includes an @context element in the payload body.

-

6.3.9 Csource Notification behaviour

-

In the HTTP binding a csource notification that is triggered by a csource subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the csource subscription structure (defined by clauses 5.2.12 and 5.2.14). The MIME type associated to the POST request shall be “application/json” by default. However, this can be changed to ”application/ld+json” by means of the endpoint.accept member.

-

If the target MIME type is “application/json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP Header for each member named “key” of the key, value pairs that make up the array shall be generated and included in the HTTP POST’s list of headers. The content of each custom header shall be set equal the content of the corresponding “value” member of the KeyValuePair. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

6.3.10 Pagination behaviour

-

For HTTP operations corresponding to the operations listed in clause 4.12 (see Table 6.2‑1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.3.10‑1.

-
-

Table 6.3.10-1: Pagination: limit parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Integer -
-0..1 -
-

Only values greater or equal to 0.

-

It defines the limit to the number of NGSI-LD Elements that shall be retrieved at a maximum as mandated by clause 5.5.9. The value 0 is only allowed in combination with the count URI parameter.

-
-

This clause defines the specific HTTP binding mechanisms that shall be used in conjunction with the behaviours defined by clause 5.5.9. Particularly, to flag the existence of related pages that could be retrieved when dealing with query operations involving pagination, NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header field as mandated by IETF RFC 8288 [7], clause 3, as follows:

-
- -
-
- -
-
- -
-
-
-

EXAMPLE:

-
-
-

If the media type requested originally was “application/json” then during the entire pagination iteration the value of the Link Target Attribute “type” shall be “application/json”.

-
-
-

If the transparent pagination option as described in clause 5.5.9.2 is used, the URI-references for the “next” and“prev” link to the next and previous pages respectively should include the limit parameter as specified in Table 6.3.10-1 and the offset parameter as specified in Table 6.3.10‑2, giving the Context Consumer more control, i.e. to adapt the size of the page using limit and jump to a desired set of elements in the results using offset.

-
-

Table 6.3.10-2: Pagination: offset parameter

-
- ------ - - - - - - - - - - - - - - - - -
-

Name

-
-

Data Type

-
-

Cardinality

-
-

Remarks

-
-offset -
-Integer -
-0..1 -
-

Only values greater or equal to 0.

-

It defines the offset of the first NGSI-LD Element that shall be retrieved from the beginning of the result set. If offset is set to a value larger than the result set, the offset should be assumed to be equal to the size of the result set, i.e. only the last element of the result set is to be returned if there are any results.

-
-

Temporal representation of resources adds an additional dimension to the pagination. Depending on the requested time range, the response will contain multiple instances of the requested Attribute, and therefore an additional pagination mechanism for those temporal representations is required, in order to limit the time range of the response. If no limits are specified, a default limit is enforced, depending on implementation specific configurations. For HTTP operations on TemporalEvolutionof Entities, implementations shall use the Partial Content Response (206) as specified by IETF RFC 7233 [31], clause 4.1, if the implementation is not able to respond with the full representation at once. In this case, for requests where the parameter lastN is present, pagination shall happen “backwards” (from the most recent to the least recent timestamp in the requested time range). For requests without the parameter lastN, pagination shall happen “forwards” (from the least recent to the most recent timestamp in the requested time range).

-

This is achieved by including the “Content-Range” header field with the following contents:

-
- -
-
- -
-
- -
-
- -
-
- -
-

6.3.11 Including system Attributes

-

For HTTP GET operations performed over the resources /entities/, /subscriptions/, /csourceRegistrations/, /csourceSubscriptions/, /temporal/entities/ and all of its sub-resources, and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.11‑1. Implementations shall not raise an error if they do not hold system generated temporal attributes.

-
-

Table 6.3.11-1: Including system generated temporal attributes: options parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-options -
-Comma separated list of strings -
-0..1 -
-When its value includes the keyword “sysAttrs”, a representation of NGSI-LD Elements shall be provided so that the system generated temporal attributes createdAt, modifiedAt and the system temporal attributeexpiresAt are included in the response payload body where known. In the case of temporal representations, also the system generated temporal attribute deletedAt is included, if the NGSI-LD Element has been deleted. -
-

6.3.12 Simplified or aggregated temporal representation of Entities

-

For HTTP GET and POST operations corresponding to “Retrieve Temporal Evolution of an Entity” (see clause 5.7.3) and “Query Temporal Evolution of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.12‑1.

-
-

Table 6.3.12-1: Temporal Entity representations: format + options parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

It shall be one of: “temporalValues”, “aggregatedValues”.

-

When its value is “temporalValues”, a simplified temporal representation of entities shall be provided as defined by clause 4.5.8.

-

When its value is “aggregatedValues”, an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword “temporalValues”, a simplified temporal representation of entities shall be provided as defined by clause 4.5.8.

-

When its value includes the keyword “aggregatedValues”, an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19.

-

Only one of the two keywords can be present in the values of the parameter.

-

If both format and options are present, the value of the format parameter shall take precedence.

-
-

6.3.13 Counting number of results

-

This clause implements the behaviour described in clause 4.13, in case of HTTP binding.

-

For HTTP operations corresponding to the operations listed in clause 4.12 (see Table 6.2‑1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.3.13‑1.

-
-

Table 6.3.13-1: Counting number of results: count parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-count -
-Boolean -
-0..1 -
-If true, then a special HTTP header (NGSILD-Results-Count) is set in the response. Regardless of how many entities are actually returned (maybe due to the limit URI parameter), the total number of matching results (e.g. number of Entities) is returned. -
-

This clause defines the specific HTTP binding mechanisms that can be useful to plan the limit and offset URI parameters for pagination, thus allowing to convey an overview of the number of entities in a system.

-

To get only the count itself, and no entities, the URI parameter limit may have the value “0”, and an empty array shall be returned as payload body.

-

Setting the URI parameter limit to zero without including the count URI parameter will result in a 400 BadRequest error.

-

6.3.14 Tenant specification

-

If the system implementing the NGSI-LD API supports multi-tenancy as described in clause 4.14 and clause 5.5.10, the Tenant, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header “NGSILD-Tenant”, whose value is the String identifying the Tenant. In case the target Tenant is the default Tenant, the HTTP header is omitted. If the HTTP header “NGSILD-Tenant” is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an “NGSILD-Tenant” HTTP header (clause 6.3.8).

-

6.3.15 GeoJSON representation of spatially bound entities

-

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), if the GeoJSON Accept header (“application/geo+json”) is present, implementations shall render the entities of the response in the GeoJSON format, as described in clause 5.2.29.

-

For GeoJSON representations, a GeoProperty may be selected as the geolocation to be used as the geometry within the GeoJSON payload. If no geometryProperty parameter is specified, then the location GeoProperty of the Entity is used.

-
-

Table 6.3.15-1: Selecting a geometry

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-geometryProperty -
-String -
-0..1 -
-If not present, “location” is used. -
-

6.3.16 Expiration time for cached @contexts

-

Implementations shall comply with the Expires header field (section 5.3 of IETF RFC 7234 [30]) or a max-age or s-maxage response directive of Cache-Control header field (section 5.2.2 of IETF RFC 7234 [30]) that may be present in the downloaded @context. This means that implementations shall periodically invalidate the “Cached” @contexts according to the headers mentioned above. Since origin servers do not always provide explicit expiration times, implementations should assign a heuristic (for instance according to IETF RFC 7234 [30] section 4.2.2) expiration time when an explicit time is not specified.

-

6.3.17 Distributed Operations Caching and Timeout Behaviour

-

The caching of response data received from forwarded HTTP GET requests is optionally supported by Context Brokers. For HTTP GET operations performed over the resources /entities and /entities/{entity-id}, where a Context Source Registration matches the request and a previous forwarded response has been cached and a subsequent request occurs before the Context Source Registration cacheDuration (as defined in Table 5.2.34‑1) has been reached, the result may incorporate data cached from a previous response. To indicate that data from a cache has been included in the response, the HTTP header “NGSILD-Warning” shall be included. The value shall match the IANA Warning Code [32] 110 - Response is Stale.

-

“NGSILD-Warning” HTTP headers shall also be used to indicate instances of abnormal behaviour for distributed HTTP GET operations performed over the resources /entities and /entities/{entity-id}.

-
-

Table 6.3.17-1: NGSI-LD Warning Codes

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-IANA Warning Code -
-Remarks -
-110 - Response is Stale -
-No request was made to a specified registration endpoint - data from a cached value has been reused and it has been incorporated into the response. -
-111 - Revalidation Failed -
-Although data was received from the registration endpoint within the specified timeout period, the payload of the response was invalid. This could occur if the payload was corrupted or a non-NGSI payload was received. -
-199 - Miscellaneous Warning -
-No response was received from the registration endpoint within the specified timeout period or a registration loop has been detected. -
-299 - Miscellaneous Persistent Warning -
-An error response (such as 403 - Forbidden) was received from the registration endpoint within the specified timeout period. This could occur if the Context Broker has insufficient access rights to retrieve the data. -
-

For distributed HTTP GET operations, registered context sources should always respond with a valid NGSI-LD payload. The Context Broker shall successfully parse this data and invalid non-NGSI-LD payloads shall be rejected and not incorporated into the overall response. It should be noted that a registration endpoint responding with no data and the HTTP status code 404 - Not Found should not be considered as abnormal behaviour for distributed operations.

-

For all other operations, which correspond to HTTP Unsafe methods, the error response should be as informative as possible.

-

In the case of an exclusive or redirect registration, where all of the data is held outside of the Context Broker and held in a single registered source, the following errors shall be returned:

-
- -
-

In the case of an inclusive or redirect registration, where an entity is distributed over multiple equally valid endpoints, but when updating the state of the distributed entity, an error response is returned from one or more registered sources:

-
- -
-

In the case of an auxiliary registration HTTP unsafe methods are not supported.

-

Whenever failures or timeouts occur, Context Brokers may optionally decline to make subsequent requests to the same registration endpoint until the cooldown period (as defined inTable5.2.9-1) has been reached.

-

6.3.18 Limiting Distributed Operations

-

The parameter described in this clause limits the execution of an operation to a local Context Source or Context Broker (clause 5.5.13). It amends the matching Context Source Registrations behaviour as described in clause 5.12, in the case of the HTTP binding in order to avoid cascading distributed operations (see clause 4.3.6.4). For all operations the resources /entities/, /types/, /attributes/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ (and their respective child resources) implementations shall support the HTTP query parameter specified in Table 6.3.18‑1. The Registry API operations are always local and thus are not included here. Operations on a Snapshot (see clause 5.5.15) are always implicitly local scope, overriding setting the local parameter to false, i.e. such a setting is to be ignored by implementations.

-
-

Table 6.3.18-1: Limiting distributed operations: local parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-local -
-Boolean -
-0..1 -
-If local=true then no Context Source Registrations shall be considered as matching to avoid cascading distributed operations (see clause 4.3.6.4). -
-

Furthermore, to avoid infinite loops, for all operations, the resources /entities/, /types/, /attributes/, /subscriptions/, /csourceSubscriptions/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ implementations shall fully support the HTTP Via Header (IETF RFC 7230 [27]) as specified in Table 6.3.18‑2. AnyContext Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source hostAlias (see clause 5.2.40) as the pseudonym.

-
-

Table 6.3.18-2: Request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-Via -
-String as defined in IETF RFC 7230 [27] -
-0..1 -
-If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations. -
-

6.3.19 Extra information to provide when contacting Context Source

-

As specified in clauses 4.3.6.5 and 4.3.6.6, extra information to be provided when contacting a Context Source can be specified in the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration.

-

In the HTTP binding, if the “jsonldContext” key is present, the URL value is placed in an HTTP Link Header as described by the JSON-LD specification [2], section 6.2 and, whenever a payload body is present in the request, the HTTP Content-Type Header is set to “application/json”. For all other keys, a new custom HTTP header is added for each member named “key” of the key-value pairs that make up the array shall be generated and included in the HTTP list of headers. The content of each custom header shall be set equal to the content of the corresponding “value” member of the KeyValuePair, unless the special value “urn:ngsi-ld:request” has been set, in which case the value is to be taken from the triggering request, if present there. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

Headers derived from other elements of the CSourceRegistration, e.g. ”NGSILD-Tenant”, take precedence and cannot be overridden using contextSourceInfo. The same applies for headers generally set by HTTP itself, e.g. Content-length.

-

6.3.20 Invalid parameters

-

If an HTTP request for an operation contains parameters that are incompatible with the operation, or it contains values of the options parameter that are not supported by the operation, an HTTP error response of type InvalidRequest should be returned.

-

6.3.21 Optional profile information regarding versioning and datatype conformance

-

In the HTTP Binding, if an HTTP

-

Link header with a

-

profile

-

parameter

-

in accordance with IETF RFC 6906 [33], is found set to [<https://uri.etsi.org/ngsi-ld/profile/version]{.HTML_Code}> then implementations that are only partially capable of interpreting the datatypes conformant to the supplied NGSI-LD version may use this information to allow the payload to be accepted within the constraints of the current implementation (see clause 5.5.4) through amending the payload body and applying the fallbacks defined within clause 4.3.6.8.

-

6.3.22 Snapshot specification

-

If the system implementing the NGSI-LD API supports Snapshots as described in clause 4.3.7 and clause 5.5.15, the Snapshot, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header “NGSILD-Snapshot”, whose value is the identifier of the Snapshot. If the HTTP header “NGSILD-Snapshot” is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an “NGSILD-Snapshot” HTTP header (clause 6.3.8).

-

6.4 Resource: entities/

-

6.4.1 Description

-

This resource represents the entities known to an NGSI-LD system.

-

6.4.2 Resource definition

-

Resource URI:

-
- -
-

6.4.3 Resource methods

-

6.4.3.1 POST

-

This method is bound to the operation “Create Entity” and shall exhibit the behaviour defined by clause 5.6.1, taking the entity to be created from the HTTP request payload body. Figure 6.4.3.1‑1 shows the Create Entity interaction and Table 6.4.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.4.3.1-1: Create Entity interaction

-
-
-

Table 6.4.3.1-1: Create Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the entity that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

The HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail member should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the entity or an exclusive or redirect registration defining the entity already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable Entity -
-

It is used to indicate that the operation is not available, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.4.3.2 GET

-

This method is associated to the operation “Query Entities” and shall exhibit the behaviour defined by clause 5.7.2, providing entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Query Entities” operations via POST is defined in clause 6.23. Figure 6.4.3.2‑1 shows the query entities interaction.

-
-

-
-
-

Figure 6.4.3.2-1: Query Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.4.3.2‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.2‑2 and Table 6.4.3.2‑3 describes the request body and possible responses.

-
-

Table 6.4.3.2-1: Query Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list of strings -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-

A synonym for a combination of the pick andq members. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entities and also included in the response, i.e. only Entities that contain at least one of the Attributes in attrs are to be included in the response, and only the Attributes listed in attrs are to be included in each of the Entities of the response.

-
-collation -
-String -
-0..1 -
-An ICU collation (see IETF RFC 6067 [36]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. -
-containedBy -
-Comma separated list of URIs -
-0..1 -
-List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present. -
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 [17] format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-expandValues -
-Comma separated list of strings -
-0..1 -
-Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query. -
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the top-level geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored unless a geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-join -
-String -
-0..1 -
-The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: “flat”, “inline”,“@none” . -
-joinLevel -
-Positive Integer -
-0..1 -
-

Depth of Linked Entity retrieval to apply.

-

Only applicable if join parameter is present.

-
-jsonKeys -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute (Property or Relationship) name.

-

Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query.

-
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-orderBy -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or an Attribute name) appended with an optional sorting style (“asc”, “desc”, “dist-asc”, “dist-desc”)as per clause 4.23. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. -
-orderFrom -
-String -
-

0..1

-

It shall be one if orderBy uses order by distance

-
-Coordinates of a Geometry serialized as a string as per clause 4.10. It is part of Entity ordering. -
-orderGeometry -
-String -
-0..1 -
-A Geometry type (with the exception of GeometryCollection) as defined by the GeoJSON specification (IETF RFC 7946 [8]). It is part of Entity ordering. -
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-splitEntities -
-Boolean -
-0..1 -
-

If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally.

-

The parameter does not apply in case localis true.

-

The default value should be decided by implementation; it should be configurable.

-
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.4.3.2-2: Query Entities request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query operation is returned in the response. -
-
-

Table 6.4.3.2-3: Query Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

Entity[]

-
-

1

-
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of entities, unless the Accept Header indicates that the Entities are to be rendered as GeoJSON.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-

Entity[]

-
-

1

-
-

203 Non-Authoritative Information

-
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-GeoJSON FeatureCollection -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7. -
-

6.4.3.3 DELETE

-

This method is associated to the operation “Purge Entities” and shall exhibit the behaviour defined by clause 5.6.21, providing entities as part of the HTTP response payload body. Figure 6.4.3.3‑1 shows the query entities interaction.

-
-

-
-
-

Figure 6.4.3.3-1: Purge Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.4.3.3‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.3‑2 and Table 6.4.3.3‑3 describes the request body and possible responses.

-
-

Table 6.4.3.3-1: Purge Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-drop -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute name.

-

When defined, every Entity within the payload body is reduced to not contain the listed Entity members.

-
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the top-level geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored unless a geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-keep -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute name.

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.4.3.3-2: Purge Entities request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the set of Entities requested during the purge operation. The location of the EntityMap used in the purge operation is returned in the response. -
-
-

Table 6.4.3.3-3: Purge Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.5 Resource: entities/{entityId}

-

6.5.1 Description

-

This resource represents an entity known to an NGSI-LD system.

-

6.5.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.5.2‑1.

-
-

Table 6.5.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the entity to be retrieved -
-

6.5.3 Resource methods

-

6.5.3.1 GET

-

This method is associated to the operation “Retrieve Entity” and shall exhibit the behaviour defined by clause 5.7.1. The Entity identifier is the value of the resource URI variable “entityId”. Figure 6.5.3.1‑1 shows the retrieve entity interaction.

-
-

-
-
-

Figure 6.5.3.1-1: Retrieve Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.1‑1, the request headers that shall be supported by implementations are those defined in Table 6.5.3.1‑2 and Table 6.5.3.1‑3 describes the request body and possible responses.

-
-

Table 6.5.3.1-1: Retrieve Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list of strings -
-0..1 -
-

A synonym for the pick parameter, except that id, type, scope are not allowed. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entity and included in the response. If the Entity does not have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not specified, no matching is performed and all Attributes related to the Entity shall be retrieved.

-
-containedBy -
-Comma separated list of URIs -
-0..1 -
-List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 [17] format, for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-geometryProperty -
-String -
-0..1 -
-

It represents a GeoProperty name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the “geometry” element. By default, it shall be location.

-
-join -
-String -
-0..1 -
-The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: “flat”, “inline”, “@none” . -
-joinLevel -
-Positive Integer -
-0..1 -
-

Depth of Linked Entity retrieval to apply. Default is 1

-

Only applicable if join parameter is: “flat” or “inline”.

-
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). When defined, the listed Entity members are removed from the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval). -
-pick -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). When defined, the Entity is reduced down to only contain the listed Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval). -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.5.3.1-2: Retrieve Entity request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the extent of the Entity data requested during the retrieval operation. The location of the EntityMap used in the retrieval operation is returned in the response. -
-
-

Table 6.5.3.1-3: Retrieve Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

Entity

-
-

1

-
-

200 OK

-
-

A response body containing the JSON-LD representation of the target entity which consists only of the selected Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-

Entity

-
-

1

-
-

203 Non-Authoritative Information

-
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-GeoJSON Feature -
-1 -
-200 OK -
-

If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7. -
-

6.5.3.2 DELETE

-

This method is associated to the operation “Delete Entity” and shall exhibit the behaviour defined by clause 5.6.6. The Entity identifier is the value of the resource URI variable “entityId”. Figure 6.5.3.2‑1 shows the delete entity interaction.

-
-

-
-
-

Figure 6.5.3.2-1: Delete Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.2‑1 and Table 6.5.3.2‑2 describes the request body and possible responses.

-
-

Table 6.5.3.2-1: Delete Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.5.3.2-2: Delete Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.5.3.3 PUT

-

This method is bound to the “Replace Entity” operation and shall exhibit the behaviour defined by clause 5.6.18. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.3‑1 shows the Replace Entity interaction.

-
-

-
-
-

Figure 6.5.3.3-1: Replace Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.3‑1 and Table 6.5.3.3‑2 describes the request body and possible responses.

-
-

Table 6.5.3.3-1: Replace Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.5.3.3-2: Replace Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Entity to be replaced.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-The entity was replaced successfully. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

6.5.3.4 PATCH

-

This method is bound to the “Merge Entity” operation and shall exhibit the behaviour defined by clause 5.6.17. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.4‑1 shows the Merge Entity interaction.

-
-

-
-
-

Figure 6.5.3.4-1: Merge Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.4‑1 and Table 6.5.3.4‑2 describes the request body and possible responses.

-
-

Table 6.5.3.4-1: Merge Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

It shall be one of: “simplified” (or its synonym “keyValues”). Where present it indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4.

-

In this case, when a merge operation applies to an existing Attribute the type field of the Attribute shall remain unchanged (any attempt to modify the type of an

-

Attribute shall result in a BadRequest error).

-
-lang -
-String -
-0..1 -
-

It represents the natural language of data held in the request.

-

When a merge operation applies to a pre-existing LanguageProperty and the value is supplied as a string or string array in the payload body, this query parameter shall be used to determine the key within the languageMap JSON Object to update.

-
-observedAt -
-String -
-0..1 -
-

It shall be a DateTime (see clause 4.6.3).

-

When a merge operation applies to a pre-existing Attribute which previously contained an observedAt sub-attribute, the value held in this query parameter shall be used if no specific observedAt sub-Attribute is found in the payload body.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword “simplified” (or its synonym “keyValues”), this indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4.

-

If both format and options are present, the value of the format parameter shall take precedence.

-
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.5.3.4-2: Merge Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be merged.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were merged successfully. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

6.6 Resource: entities/{entityId}/attrs/

-

6.6.1 Description

-

This resource represents all the Attributes (Properties or Relationships) of an NGSI-LD Entity.

-

6.6.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.6.2‑1.

-
-

Table 6.6.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-

6.6.3 Resource methods

-

6.6.3.1 POST

-

This method is bound to the “Append Attributes” operation and shall exhibit the behaviour defined by clause 5.6.3. The Entity identifier is the value of the resource URI variable “entityId”. The data to be appended shall be contained in the HTTP request payload body. Figure 6.6.3.1‑1 shows the Append Attributes interaction.

-
-

-
-
-

Figure 6.6.3.1-1: Append Attributes interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.6.3.1‑1 and Table 6.6.3.1‑2 describes the request body and possible responses.

-
-

Table 6.6.3.1-1: Append Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-options -
-Comma separated list of strings -
-0..1 -
-“noOverwrite” indicates that no attribute overwrite shall be performed. -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.6.3.1-2: Append Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be added.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were appended successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

Only the Attributes included in the response payload body were successfully appended.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.6.3.2 PATCH

-

This method is bound to the “Update Attributes” operation and shall exhibit the behaviour defined by clause 5.6.2. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.6.3.2‑1 shows the Update Attributes interaction.

-
-

-
-
-

Figure 6.6.3.2-1: Update Attributes interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.6.3.2‑1 and Table 6.6.3.2‑2 describes the request body and possible responses.

-
-

Table 6.6.3.2-1: Update Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.6.3.2-2: Update Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were updated successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the updated array of UpdateResult (see clause 5.2.18) will be empty.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

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

-

6.7.1 Description

-

This resource represents an attribute (Property or Relationship) of an NGSI-LD Entity.

-

6.7.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.7.2‑1.

-
-

Table 6.7.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-

6.7.3 Resource methods

-

6.7.3.1 PATCH

-

This method is bound to the “Partial Attribute Update” operation and shall exhibit the behaviour defined by clause 5.6.4. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. The Entity Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.1-1 shows the Partial Attribute Update interaction.

-
-

-
-
-

Figure 6.7.3.1-1: Partial Attribute Update interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.7.3.1‑1 and Table 6.7.3.2‑2 describes the request body and possible responses.

-
-

Table 6.7.3.1-1: Partial Attribute Update URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.7.3.1-2: Partial Attribute Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing the elements of the attribute to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The attribute was updated successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2. -
-

6.7.3.2 DELETE

-

This method is associated to the operation “Delete Attribute” and shall exhibit the behaviour defined by clause 5.6.5. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. Figure 6.7.3.2‑1 shows the Delete Attribute interaction, Table 6.7.3.2‑1 shows the delete parameters to be supported and Table 6.7.3.2‑2 describes the request body and possible responses.

-
-

-
-
-

Figure 6.7.3.2-1: Delete Attribute interaction

-
-
-

Table 6.7.3.2-1: Delete Attribute URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-datasetId -
-String -
-0..1 -
-Shall be a valid URI. Specifies the datasetId of the dataset to be deleted. -
-deleteAll -
-Boolean -
-0..1 -
-If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted. -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.7.3.2-2: Delete Attribute request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) or attribute name not known to the system. see clause 6.3.2. -
-

6.7.3.3 PUT

-

This method is bound to the “Replace Attribute” operation and shall exhibit the behaviour defined by clause 5.6.19. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. The Attribute Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.3‑1 shows the Replace Attribute interaction.

-
-

-
-
-

Figure 6.7.3.3-1: Replace Attribute interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.7.3.3‑1 and Table 6.7.3.3‑2 describes the request body and possible responses.

-
-

Table 6.7.3.3-1: Replace Attribute URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.7.3.3-2: Replace Attribute request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Attribute Fragment

-
-

1

-
-

Attribute Fragment replacing the previous data.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The attribute was replaced successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2. -
-

6.8 Resource: csourceRegistrations/

-

6.8.1 Description

-

This resource represents the context source registrations known to an NGSI-LD system.

-

6.8.2 Resource definition

-

Resource URI:

-
- -
-

6.8.3 Resource methods

-

6.8.3.1 POST

-

This method is bound to the operation “Register Context Source” and shall exhibit the behaviour defined by clause 5.9.2, taking the context source registration to be created from the HTTP request payload body. Figure 6.8.3.1‑1 shows the Register Context Source interaction and Table 6.8.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.8.3.1-1: Register Context Source interaction

-
-
-

Table 6.8.3.1-1: Register Context Source request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

CSourceRegistration

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created context source registration. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the context source registration already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-

422 Unprocessable

-

Context Source Registration

-
-

It is used to indicate that the operation is not available see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.8.3.2 GET

-

This method is associated to the operation “Query Context Source Registrations” and shall exhibit the behaviour defined by clause 5.10.2, i.e. the parameters in the request describe entity related information, but instead of directly providing this entity information, the context source registration data, which describes context sources that can possibly provide the information, are returned as part of the HTTP response payload body. Figure 6.8.3.2‑1 shows the Query Context Source Registrations interaction.

-
-

-
-
-

Figure 6.8.3.2-1: Query Context Source Registrations interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.8.3.2‑1 and Table 6.8.3.2-2 describes the request body and possible responses.

-
-

Table 6.8.3.2-1: Query Context Source Registrations URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list strings -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-

A synonym for a combination of the pick andq members. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.

-
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-endTimeAt -
-String -
-0..1 -
-

It represents the endTimeAt parameter as defined by clause 4.1.

-

It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between”.

-
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present.

-

At least one among: type, attrs, q, or georel shall be present.

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the top-level geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored if no geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids satisfying the query -
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). -
-pick -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). -
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-timeAt -
-String -
-0..1 -
-

It represents the timeAt parameter as defined by clause 4.1.

-

It shall be a DateTime. Cardinality shall be 1 if timerel is present.

-
-timeproperty -
-String -
-

0..1

-

It shall be ignored if no temporal query is present.

-
-

It represents a Temporal Property name.

-

Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8).

-
-timerel -
-String -
-0..1 -
-

It represents the temporal relationship as defined by clause 4.1.

-

Allowed values: “before”, “after”, “between”.

-
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.8.3.2-2: Retrieve Context Source Registrations request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-CSourceRegistration[] -
-1 -
-200 OK -
-A response body containing the query result as an array of context source registrations. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.9 Resource: csourceRegistrations/{registrationId}

-

6.9.1 Description

-

This resource represents the context source registration, identified by registrationId, known to an NGSI-LD system.

-

6.9.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.9.2‑1.

-
-

Table 6.9.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-registrationId -
-Id (URI) of the context source registration -
-

6.9.3 Resource methods

-

6.9.3.1 GET

-

This method is associated with the operation “Retrieve Context Source Registration” and shall exhibit the behaviour defined by clause 5.10.1. The registration identifier is the value of the resource URI variable “registrationId”. Figure 6.9.3.1-1 shows the Retrieve Context Source Registration interaction and Table 6.9.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.1-1: Retrieve Context Source Registration interaction

-
-
-

Table 6.9.3.1-1: Retrieve Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-CSourceRegistration -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target context source registration. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2. -
-

6.9.3.2 PATCH

-

This method is bound to the “Update Context Source Registration” operation and shall exhibit the behaviour defined by clause 5.9.3. The context source registration identifier is the value of the resource URI variable “registrationId”. The context source registration to be updated shall be contained in the HTTP request payload body. Figure 6.9.3.2‑1 shows the Update Context Source Registration interaction and Table 6.9.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.2-1: Update Context Source Registration interaction

-
-
-

Table 6.9.3.2-1: Update Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

CSourceRegistration Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration that is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The context source registration was successfully updated. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier not known to the system, see clause 6.3.2. -
-

6.9.3.3 DELETE

-

This method is associated to the operation “Delete Context Source Registration” and shall exhibit the behaviour defined by clause 5.9.4. The context source registration identifier is the value of the resource URI variable “registrationId”. Figure 6.9.3.3‑1 shows the Delete Context Source Registration interaction and Table 6.9.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.3-1: Delete Context Source Registration interaction

-
-
-

Table 6.9.3.3-1: Delete Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2. -
-

6.10 Resource: subscriptions/

-

6.10.1 Description

-

This resource represents the subscriptions known to an NGSI-LD system.

-

6.10.2 Resource definition

-

Resource URI:

-
- -
-

6.10.3 Resource methods

-

6.10.3.1 POST

-

This method is bound to the operation “Create Subscription” and shall exhibit the behaviour defined by clause 5.8.1, taking the subscription to be created from the HTTP request payload body. Figure 6.10.3.1‑1 shows the Create Subscription interaction and Table 6.10.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.10.3.1-1: Create Subscription interaction

-
-
-

Table 6.10.3.1-1: Create Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the subscription that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the subscription already exists see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.10.3.2 GET

-

This method is associated to the operation “Query Subscriptions” and shall exhibit the behaviour defined by clause 5.8.4, providing the subscription data as part of the HTTP response payload body. Figure 6.10.3.2‑1 shows the Query Subscriptions interaction.

-
-

-
-
-

Figure 6.10.3.2-1: Query Subscriptions interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.10.3.2‑1 and Table 6.10.3.2-2 describes the request body and possible responses.

-
-

Table 6.10.3.2-1: Query Subscriptions URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Number -
-0..1 -
-Maximum number of subscriptions to be retrieved -
-
-

Table 6.10.3.2-2: Query Subscriptions request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription[] -
-1 -
-200 OK -
-A response body containing a list of subscriptions. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.11 Resource: subscriptions/{subscriptionId}

-

6.11.1 Description

-

This resource represents a subscription known to an NGSI-LD system.

-

6.11.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.11.2‑1.

-
-

Table 6.11.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-subscriptionId -
-Id (URI) of the concerned subscription -
-

6.11.3 Resource methods

-

6.11.3.1 GET

-

This method is associated to the operation “Retrieve Subscription” and shall exhibit the behaviour defined by clause 5.8.3. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.1‑1 shows the Retrieve Subscription interaction and Table 6.11.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.1-1: Retrieve Subscription interaction

-
-
-

Table 6.11.3.1-1: Retrieve Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.11.3.2 PATCH

-

This method is associated to the operation “Update Subscription” and shall exhibit the behaviour defined by clause 5.8.2. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.2‑1 shows the Update Subscription interaction and Table 6.11.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.2-1: Update Subscription interaction

-
-
-

Table 6.11.3.2-1: Update Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription Fragment

-
-

1

-
-

Subscription Fragment including id, type and any other subscription field to be changed

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.11.3.3 DELETE

-

This method is associated to the operation “Delete Subscription” and shall exhibit the behaviour defined by clause 5.8.5. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.3‑1 shows the Delete Subscription interaction and Table 6.11.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.3-1: Delete Subscription interaction

-
-
-

Table 6.11.3.3-1: Delete Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.12 Resource: csourceSubscriptions/

-

6.12.1 Description

-

This resource represents the context source registration subscriptions known to an NGSI-LD system.

-

6.12.2 Resource definition

-

Resource URI:

-
- -
-

6.12.3 Resource methods

-

6.12.3.1 POST

-

This method is bound to the operation “Create Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.2, taking the context source registration subscription to be created from the HTTP request payload body. Figure 6.12.3.1‑1 shows the Create Context Source Registration Subscription interaction and Table 6.12.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.12.3.1-1: Create Context Source Registration Subscription interaction

-
-
-

Table 6.12.3.1-1: Create Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration subscription that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created context source registration subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the context source registration subscription already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.12.3.2 GET

-

This method is associated to the operation “Query Context Source Registration Subscriptions” and shall exhibit the behaviour defined by clause 5.11.5, providing the context source registration subscription data as part of the HTTP response payload body. Figure 6.12.3.2‑1 shows the Query Context Source Registration Subscriptions interaction.

-
-

-
-
-

Figure 6.12.3.2-1: Query Context Source Registration Subscriptions interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.12.3.2‑1 and Table 6.12.3.2-2 describes the request body and possible responses.

-
-

Table 6.12.3.2-1: Query Context Source Registration Subscriptions URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Number -
-0..1 -
-Maximum number of subscriptions to be retrieved -
-
-

Table 6.12.3.2-2: Query Context Source Registration Subscriptions request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription[] -
-1 -
-200 OK -
-A response body containing a list of context source registration subscriptions. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.13 Resource: csourceSubscriptions/{subscriptionId}

-

6.13.1 Description

-

This resource represents the context source registration subscription, identified by subscriptionId, known to an NGSI-LD system.

-

6.13.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.13.2‑1.

-
-

Table 6.13.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-subscriptionId -
-Id (URI) of the concerned context source registration subscription. -
-

6.13.3 Resource methods

-

6.13.3.1 GET

-

This method is associated to the operation “Retrieve Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.4. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.1‑1 shows the Retrieve Context Source Registration interaction and Table 6.13.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.1-1: Retrieve Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target context source registration subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.13.3.2 PATCH

-

This method is associated to the operation “Update Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.3. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.2‑1 shows the Update Context Source Registration Subscription interaction and Table 6.13.3.2-1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.2-1: Update Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.2-1: Update Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription Fragment

-
-

1

-
-

Subscription Fragment including id, type and any other context source registration subscription field to be changed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.13.3.3 DELETE

-

This method is associated to the operation “Delete Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.6. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.3‑1 shows the Delete Context Source Registration Subscription interaction and Table 6.13.3.3-1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.3-1: Delete Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.3-1: Delete Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.14 Resource: entityOperations/create

-

6.14.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation for the NGSI-LD API.

-

6.14.2 Resource definition

-

Resource URI:

-
- -
-

6.14.3 Resource methods

-

6.14.3.1 POST

-

This method is associated to the operation “Batch Entity Creation” and shall exhibit the behaviour defined by clause 5.6.7. Figure 6.14.3.1‑1 shows the operation interaction and Table 6.14.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.14.3.1-1: Batch Entity Creation interaction

-
-
-

Table 6.14.3.1-1: Batch Entity Creation request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of entities to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-String[] -
-1 -
-201 Created -
-If all entities have been successfully created, an array of Strings containing URIs is returned in the response. Each URI represents the Entity ID of a created entity. There is no restriction as to the order of the Entity IDs. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created entities, while the second array (errors) contains information about the error for each of the entities that could not be created. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.15 Resource: entityOperations/upsert

-

6.15.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation or update for the NGSI-LD API.

-

6.15.2 Resource definition

-

Resource URI:

-
- -
-

6.15.3 Resource methods

-

6.15.3.1 POST

-

This method is associated to the operation “Batch Entity Creation or Update (Upsert)” and shall exhibit the behaviour defined by clause 5.6.8. Figure 6.15.3.1‑1 shows the operation interaction and Table 6.15.3.1‑1 describes the request body and possible responses.

-

The options query parameter for this request can take the following values:

-
- -
-
-

-
-
-

Figure 6.15.3.1-1: Batch Entity Creation or Update interaction

-
-
-

Table 6.15.3.1-1: Batch Entity Creation or Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of entities to be created/updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-String[] -
-1 -
-201 Created -
-If all entities not existing prior to this request have been successfully created and the others have been successfully updated, an array of String (with the URIs representing the Entity IDs of the created entities only) is returned in the response. There is no restriction as to the order of the Entity IDs. The merely updated entities do not take part in the response (corresponding to 204 No Content returned in the case of updates). -
-N/A -
-N/A -
-204 No Content -
-If all entities already existed and are successfully updated, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created or updated entities, while the second array (errors) contains information about the error for each of the entities that could not be created or updated. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.16 Resource: entityOperations/update

-

6.16.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity update for the NGSI-LD API.

-

6.16.2 Resource definition

-

Resource URI:

-
- -
-

6.16.3 Resource methods

-

6.16.3.1 POST

-

This method is associated to the operation “Batch Entity Update” and shall exhibit the behaviour defined by clause 5.6.9. Figure 6.16.3.1‑1 shows the operation interaction and Table 6.16.3.1‑1 describes the request body and possible responses.

-

The options query parameter for this request can take the following values:

-
- -
-
-

-
-
-

Figure 6.16.3.1-1: Batch Entity Update interaction

-
-
-

Table 6.16.3.1-1: Batch Entity Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of Entities to be updated

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities have been successfully updated, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully updated entities, while the second array (errors) contains information about the error for each of the entities that could not be updated. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.17 Resource: entityOperations/delete

-

6.17.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity deletion for the NGSI-LD API.

-

6.17.2 Resource definition

-

Resource URI:

-
- -
-

6.17.3 Resource methods

-

6.17.3.1 POST

-

This method is associated to the operation “Batch Entity Delete” and shall exhibit the behaviour defined by clause 5.6.10. Figure 6.17.3.1‑1 shows the operation interaction and Table 6.17.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.17.3.1-1: Batch Entity Delete interaction

-
-
-

Table 6.17.3.1-1: Batch Entity Delete request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

String[]

-
-

1

-
-

Array of String (URIs representing Entity IDs) to be deleted

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities existed and have been successfully deleted, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully deleted entities, while the second array (errors) contains information about the error for each of the entities that could not be deleted. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.18 Resource: temporal/entities/

-

6.18.1 Description

-

This resource represents the TemporalEvolution of Entities known to an NGSI-LD system.

-

6.18.2 Resource definition

-

Resource URI:

-
- -
-

6.18.3 Resource methods

-

6.18.3.1 POST

-

This method is associated to the operation “Create or Update Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.11, taking the temporal representation of Entity to be created from the HTTP request payload body. Figure 6.18.3.1‑1 shows this interaction and Table 6.18.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity interaction

-
-
-

Table 6.18.3.1-1: Create or Update Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the temporal representation of the Entity that is to be created (or updated).

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-Upon creation success, the HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity. -
-N/A -
-N/A -
-204 No Content -
-Upon update success. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail member should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable Entity -
-

It is used to indicate that the operation is not available, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.18.3.2 GET

-

This method is associated to the operation “Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.7.4, providing the Temporal Evolution of the matching Entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Query Temporal Evolution of Entities” operations via POST is defined in clause 6.24. Figure 6.18.3.2‑1 shows this interaction.

-
-

-
-
-

Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.18.3.2‑1 and Table 6.18.3.2-2 describes the request body and possible responses.

-
-

Table 6.18.3.2-1: Query Temporal Evolution of Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-aggrMethods -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if aggregatedValues is present in the options parameter

-
-Each String represents an aggregation method, as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-attrs -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if type is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-

A synonym for a combination of the pick andq parameters. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.

-
-collation -
-String -
-0..1 -
-An ICU collation (see IETF RFC 6067 [36]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. -
-coordinates -
-String -
-

0..1

-

It shall be one if georel or geometry are present

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-endTimeAt -
-String -
-0..1 -
-It is representing the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between”. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 [17] format, for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-expandValues -
-Comma separated list of strings -
-0..1 -
-Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query. -
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geoproperty -
-String -
-

0..1

-

It shall be ignored if no geoquery is present

-
-The name of the GeoProperty that contains the geospatial data that will be used to resolve the geoquery. By default, will be location. (See clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-jsonKeys -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute (Property or Relationship) name.

-

Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query.

-
-lang -
-String -
-0..1 -
-It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language. -
-lastN -
-Positive integer -
-0..1 -
-Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. -
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-orderBy -
-String -
-0..1 -
-The Entity member (“id”) appended with an optional sorting style (“asc”, “desc”)as per clause 4.23. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. -
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-0..1 -
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-splitEntities -
-Boolean -
-0..1 -
-

If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally.

-

The parameter does not apply in case localis true.

-

The default value should be decided by implementation; it should be configurable.

-
-timeAt -
-String -
-1 -
-representing the timeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-timeproperty -
-String -
-0..1 -
-It represents a Temporal Property name. Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8). -
-timerel -
-String -
-1 -
-It represents the temporal relationship as defined by clause 4.11. Allowed values: “before”, “after”, “between”. -
-type -
-String -
-

0..1

-

It shall be 1 if attrs is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.18.3.2-2: Query Temporal Evolution of Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of temporal representation of Entities.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-EntityTemporal[] -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.19 Resource: temporal/entities/{entityId}

-

6.19.1 Description

-

This resource is associated to the TemporalEvolutionof an Entity known to an NGSI-LD system.

-

6.19.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.19.2‑1.

-
-

Table 6.19.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the entity to be retrieved -
-

6.19.3 Resource methods

-

6.19.3.1 GET

-

This method is associated to the operation “Retrieve Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.7.3. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.1‑1 shows the retrieve temporal representation of an entity interaction.

-
-

-
-
-

Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.19.3.1‑1 and Table 6.19.3.1‑2 describes the request body and possible responses.

-
-

Table 6.19.3.1-1: Retrieve Temporal Evolution of an Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-aggrMethods -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if aggregatedValues is present in the options parameter

-
-Each String represents the aggregation methods as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-attrs -
-Comma separated list of strings -
-0..1 -
-

A synonym for the pick parameter, except that id, type, scope are not allowed. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be retrieved. If not specified, all Attributes related to the temporal representation of an Entity shall be retrieved.

-
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-endTimeAt -
-String -
-

0..1

-

It shall be 1 if timerel is equal to “between”

-
-It represents the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-lang -
-String -
-0..1 -
-It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language. -
-lastN -
-Positive integer -
-0..1 -
-Only the last n Attribute instances (under the concerned time interval) shall be retrieved. -
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-timeAt -
-String -
-

0..1

-

It shall be 1 if timerel is present

-
-It represents the timeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-timeproperty -
-String -
-0..1 -
-It represents a Temporal Property name. Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8). -
-timerel -
-String -
-

0..1

-

It shall be 1 if timeAt is present

-
-It represents the Temporal Relationship as defined by clause 4.11. Allowed values: “before”, “after”, “between”. -
-
-

Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal -
-1 -
-200 OK -
-A response body containing the JSON-LD temporal representation of the target Entity containing the selected Attributes. -
-EntityTemporal -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.19.3.2 DELETE

-

This method is associated to the operation “Delete Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.16. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.2‑1 shows the delete entity interaction and Table 6.19.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction

-
-
-

Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

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

-

6.20.1 Description

-

This resource represents all the Attributes (Properties or Relationships) of a TemporalEvolutionof an Entity.

-

6.20.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.20.2‑1.

-
-

Table 6.20.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-

6.20.3 Resource methods

-

6.20.3.1 POST

-

This method is bound to the “Add Attributes to Temporal Evolution of an Entity” operation and shall exhibit the behaviour defined by clause 5.6.12. The Entity identifier is the value of the resource URI variable entityId. The data to be added shall be contained in the HTTP request payload body. Figure 6.20.3.1‑1 shows the Add Attributes interaction and Table 6.20.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity interaction

-
-
-

Table 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal Fragment

-
-

1

-
-

EntityTemporal Fragment containing a complete representation of the Attribute instances to be added.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were added successfully. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

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

-

6.21.1 Description

-

This resource represents an Attribute (Property or Relationship) of a TemporalEvolutionof an Entity.

-

6.21.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.21.2‑1.

-
-

Table 6.21.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-

6.21.3 Resource methods

-

6.21.3.1 DELETE

-

This method is associated to the operation “Delete Attribute from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.13. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. Figure 6.21.3.1‑1 shows the “Delete Attribute from Temporal Evolution of an Entity” interaction, Table 6.21.3.1‑1 shows the delete parameters to be supported and Table 6.21.3.1-2 describes the request body and possible responses.

-
-

-
-
-

Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity interaction

-
-
-

Table 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Cardinality -
-Remarks -
-datasetId -
-String -
-0..1 -
-Shall be a valid URI. Specifies the datasetId of the dataset to be deleted. -
-deleteAll -
-Boolean -
-0..1 -
-If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted. -
-
-

Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) or Attribute name not known to the system. See clause 6.3.2. -
-

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

-

6.22.1 Description

-

This resource represents an Attribute (Property or Relationship) instance of a TemporalEvolutionof an Entity.

-

6.22.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.22.2‑1.

-
-

Table 6.22.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-instanceId -
-Id (URI) identifying a particular Attribute instance -
-

6.22.3 Resource methods

-

6.22.3.1 PATCH

-

This method is associated to the operation “Modify attribute instance from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.14. The Entity identifier is the value of the resource URI variable entityId. The attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.1‑1 shows the Modify Attribute instance interaction and Table 6.22.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution interaction

-
-
-

Table 6.22.3.1-1: Modify Attribute instance from Temporal Evolution request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal Fragment

-
-

1

-
-

EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2. -
-

6.22.3.2 DELETE

-

This method is associated to the operation “Delete Attribute instance from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.15. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.2‑1 shows the Delete Attribute instance interaction and Table 6.22.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity interaction

-
-
-

Table 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2. -
-

6.23 Resource: entityOperations/query

-

6.23.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.4.3.2, which performs the “Query Entity” operation (defined by clause 5.7.2) by means of a GET method. The reason to provide an alternative via POST is that, using GET:

-
-
    -
  1. The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
    2. -
  2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.
    3. -
-
-

6.23.2 Resource definition

-

Resource URI:

-
- -
-

6.23.3 Resource methods

-

6.23.3.1 POST

-

This method is associated to the operation “Query Entities” and shall exhibit the behaviour defined by clause 5.7.2. Figure 6.23.3.1‑1 shows the operation interaction and Table 6.23.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.23.3.1-1: Query Entity via POST interaction

-
-
-

Table 6.23.3.1-1: Query Entity via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Entity[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of Entities.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-GeoJSON FeatureCollection -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-Entity[] -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.24 Resource: temporal/entityOperations/query

-

6.24.1 Description

-

A sub-resource, pertaining to the temporal/entityOperations/ resource, intended to enable temporal querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.18.3.2, which performs the “Query Temporal Evolution of Entities” (defined by clause 5.7.4) operation by means of a GET method. The reason to provide an alternative via POST is that, using GET:

-
-
    -
  1. The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
    2. -
  2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.
    3. -
-
-

6.24.2 Resource definition

-

Resource URI:

-
- -
-

6.24.3 Resource methods

-

6.24.3.1 POST

-

This method is associated to the operation “Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.7.4. Figure 6.24.3.1‑1 shows the operation interaction and Table 6.24.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.24.3.1-1: Temporal Query Entity via POST interaction

-
-
-

Table 6.24.3.1-1: Temporal Query Entity via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of Entities.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.25 Resource: types/

-

6.25.1 Description

-

This resource represents the entity types available in an NGSI-LD system.

-

6.25.2 Resource definition

-

Resource URI:

-
- -
-

6.25.3 Resource methods

-

6.25.3.1 GET

-

This method is associated to the operations “Retrieve Available Entity Types” and “Retrieve Details of Available Entity Types” (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.5 and 5.7.6 respectively.

-
-

-
-
-

Figure 6.25.3.1-1: Retrieve Available Entity Types interaction

-
-

The request parameters that shall be supported are those defined in Table 6.25.3.1‑1 and Table 6.25.3.1‑2 describes the request body and possible responses.

-
-

Table 6.25.3.1-1: Retrieve Available Entity Types URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-If true, then detailed entity type information represented as an array with elements of the Entity Type data structure (clause 5.2.25) is to be returned. -
-
-

Table 6.25.3.1-2: Retrieve Available Entity Types request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTypeList -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the EntityTypeList (clause 5.2.24) is to be returned, unless details=true is specified. -
-EntityType[] -
-1 -
-200 OK -
-If details=true is specified, a response body containing a JSON-LD array with elements of the EntityType data structure (clause 5.2.25) is to be returned. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.26 Resource: types/{type}

-

6.26.1 Description

-

This resource represents the specified entity type for which entity instances are available in an NGSI-LD system.

-

6.26.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.26.2‑1.

-
-

Table 6.26.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-type -
-Name of the entity type for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. -
-

6.26.3 Resource methods

-

6.26.3.1 GET

-

This method is associated to the operation “Retrieve Available Entity Type Information” and shall exhibit the behaviour defined by clause 5.7.7. The entity type is the value of the resource URI variable “type”. Figure 6.26.3.1‑1 shows the retrieve available entity type interaction.

-
-

-
-
-

Figure 6.26.3.1-1: Retrieve Available Entity Type interaction

-
-

Table 6.26.3.1‑1 describes the request body and possible responses.

-
-

Table 6.26.3.1-1: Retrieve Available Entity Type request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTypeInfo -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the detailed information about the available entity type. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an entity type not known to the system, see clause 6.3.2. -
-

6.27 Resource: attributes/

-

6.27.1 Description

-

This resource represents the attributes available in an NGSI-LD system.

-

6.27.2 Resource definition

-

Resource URI:

-
- -
-

6.27.3 Resource methods

-

6.27.3.1 GET

-

This method is associated to the operations “Retrieve Available Attributes” and “Retrieve Details of Available Attributes” (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.8 and 5.7.9 respectively.

-
-

-
-
-

Figure 6.27.3.1-1: Retrieve Available Attributes interaction

-
-

The request parameters that shall be supported are those defined in Table 6.27.3.1‑1 and Table 6.27.3.1‑2 describes the request body and possible responses.

-
-

Table 6.27.3.1-1: Retrieve Available Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-If true, then detailed attribute information represented as an array with elements of the Attribute data structure (clause 5.2.28) is to be returned. -
-
-

Table 6.27.3.1-2: Retrieve Available Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-AttributeList -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the AttributeList (clause 5.2.27) is to be returned, unless details=true is specified. -
-Attribute[] -
-1 -
-200 OK -
-If details=true is specified, a response body containing a JSON-LD array with elements of the Attribute data structure (clause 5.2.28) is to be returned. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.28 Resource: attributes/{attrId}

-

6.28.1 Description

-

This resource represents the specified attribute that belongs to entity instances existing within the NGSI-LD system.

-

6.28.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.28.2‑1.

-
-

Table 6.28.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-attrId -
-Name of the attribute for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. -
-

6.28.3 Resource methods

-

6.28.3.1 GET

-

This method is associated to the operation “Retrieve Available Attribute Information” and shall exhibit the behaviour defined by clause 5.7.10. The attribute is the value of the resource URI variable “attrId”. Figure 6.28.3.1‑1 shows the retrieve available attribute information interaction.

-
-

-
-
-

Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction

-
-

Table 6.28.3.1‑1 describes the request body and possible responses.

-
-

Table 6.28.3.1-1: Retrieve Available Attribute Information request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Attribute -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the detailed information about the available attribute. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an attribute name not known to the system, see clause 6.3.2. -
-

6.29 Resource: jsonldContexts/

-

6.29.1 Description

-

This resource represents the @contexts known to an NGSI-LD system.

-

6.29.2 Resource definition

-

Resource URI:

-
- -
-

6.29.3 Resource methods

-

6.29.3.1 POST

-

This method is bound to the operation “Add @context” and shall exhibit the behaviour defined by clause 5.13.2, taking the @context to be added from the HTTP request payload body. Figure 6.29.3.1‑1 shows the Add @context interaction and Table 6.29.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.29.3.1-1: Add @context interaction

-
-
-

Table 6.29.3.1-1: Add @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

JSON Object

-
-

1

-
-

Payload body in the request contains a JSON object that has a root node named @context, which represents a JSON-LD “local context”.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the local relative path of the added @context. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.29.3.2 GET

-

This method is associated to the operation “List @contexts” and shall exhibit the behaviour defined by clause 5.13.3, and it provides information about stored @contexts as part of the HTTP response payload body. Figure 6.29.3.2‑1 shows the List @contexts interaction.

-
-

-
-
-

Figure 6.29.3.2-1: List @contexts interaction

-
-

The request parameters that shall be supported by implementations are those defined in Table 6.29.3.2‑1 and Table 6.29.3.2-2 describes the request body and possible responses.

-
-

Table 6.29.3.2-1: List @contexts URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-Whether a list of URLs or a more detailed list of JSON Objects is requested. -
-kind -
-String -
-0..1 -
-Can be either “Cached”, “Hosted”, or “ImplicitlyCreated”. -
-
-

Table 6.29.3.2-2: List @contexts request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

String[]

-

or

-

JSON Object[]

-
-1 -
-200 OK -
-A response body containing a list of URLs or a list of JSON Objects, as defined in clause 5.13.3.5, representing metadata about stored @contexts. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.30 Resource: jsonldContexts/{contextId}

-

6.30.1 Description

-

This resource represents a JSON-LD @context stored in the broker’s internal @context storage.

-

6.30.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.30.2‑1.

-
-

Table 6.30.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-contextId -
-Local identifier of the @context to be managed (served or deleted). For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from. -
-

6.30.3 Resource methods

-

6.30.3.1 GET

-

This method is associated to the operation “Serve @context” and shall exhibit the behaviour defined by clause 5.13.4. The @context identifier is the value of the resource URI variable “contextId”. Figure 6.30.3.1‑1 shows the HTTP Serve @context interaction.

-
-

-
-
-

Figure 6.30.3.1-1: Serve @context interaction

-
-

The request parameters that shall be supported by implementations are those defined in Table 6.30.3.1‑1 and Table 6.30.3.1-2 describes the request body and possible responses.

-
-

Table 6.30.3.1-1: Serve @contexts URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-Whether the content of the @context or its metadata is requested. -
-
-

Table 6.30.3.1-2: Serve @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

JSON Object

-
-

1

-
-

200 OK

-
-

If the parameter details are false or missing, response body contains a JSON object that has a root node named @context, which represents a JSON-LD “local context”.

-

If the parameter details are true, response body contains a JSON object as defined in clause 5.13.4.5, which metadata of a JSON-LD “local context”.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

400 Bad Request

-
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable -
-It is used when a client indicated an @context of type “Cached”, see clause 6.3.2. -
-

6.30.3.2 DELETE

-

This method is associated to the operation “Delete and Reload @context” and shall exhibit the behaviour defined by clause 5.13.5. The Entity identifier is the value of the resource URI variable “contextId”. Figure 6.30.3.2‑1 shows the delete entity interaction. The request parameters that shall be supported are those defined in Table 6.30.3.2‑1 and Table 6.30.3.2-2 describes the request body and possible responses.

-
-

Table 6.30.3.2-1: Delete and Reload @context URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-reload -
-Boolean -
-0..1 -
-indicates to perform a download and replace of the @context, as specified in clause 5.13.5.4. -
-
-

-
-
-

Figure 6.30.3.2-1: Delete and Reload @context interaction

-
-
-

Table 6.30.3.2-2: Delete and Reload @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-504 Gateway Timeout -
-It is used when re-downloading fails. -
-

6.31 Resource: entityOperations/merge

-

6.31.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity merge for the NGSI-LD API.

-

6.31.2 Resource definition

-

Resource URI:

-
- -
-

6.31.3 Resource methods

-

6.31.3.1 POST

-

This method is associated to the operation “Batch Entity Merge” and shall exhibit the behaviour defined by clause 5.6.20. Figure 6.31.3.1‑1 shows the operation interaction and Table 6.31.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.31.3.1-1: Batch Entity Merge interaction

-
-
-

Table 6.31.3.1-1: Batch Entity Merge request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of Entities to be merged.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities have been successfully merged, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully merged entities, while the second array (errors) contains information about the error for each of the entities that could not be merged-patched. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.32 Resource: entityMaps/{entityMapId}

-

6.32.1 Description

-

This resource represents an EntityMap available in the broker’s internal storage or memory.

-

6.32.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.32.2‑1.

-
-

Table 6.32.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityMapId -
-Id (URI) of the EntityMap to be retrieved, updated or deleted. -
-

6.32.3 Resource methods

-

6.32.3.1 GET

-

This method is associated to the operation “Retrieve EntityMap” and shall exhibit the behaviour defined by clause 5.14.1. The EntityMap identifier is the value of the resource URI variable “entityMapId”. Figure 6.32.3.1‑1 shows the Retrieve EntityMap interaction and Table 6.32.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.1-1: Retrieve EntityMap

-
-
-

Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-Response Body -
-Data Type -
-Cardinality -
-Response Codes -
-Remarks -
-EntityMap -
-1 -
-200 OK -
-

A response body containing the JSON-LD representation of the target entity.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

404 Not Found

-
-

It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

-
-

6.32.3.2 PATCH

-

This method is associated to the operation “Update EntityMap” and shall exhibit the behaviour defined by clause 5.14.2. The EntityMap identifier is the value of the resource URI variable “entityMapId”. Figure 6.32.3.2‑1 shows the Update EntityMap interaction and Table 6.32.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.2-1: Update EntityMap

-
-
-

Table 6.32.3.2-1: Update EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityMap Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the EntityMap fragment with which the EntityMap is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2. -
-

6.32.3.3 DELETE

-

This method is associated to the operation “Delete EntityMap” and shall exhibit the behaviour defined by clause 5.14.3. The Entity identifier is the value of the resource URI variable “contextId”. Figure 6.32.3.3‑1 shows the delete entity interaction and Table 6.32.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.3-1: Delete and Reload @context interaction

-
-
-

Table 6.32.3.3-1: Delete EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-

6.33 Resource: info/sourceIdentity

-

6.33.1 Description

-

This resource represents identity information about the Context Source itself.

-

6.33.2 Resource definition

-

Resource URI:

-
- -
-

6.33.3 Resource methods

-

6.33.3.1 GET

-

This method is associated to the operation “Retrieve Context Source Identity Information” and shall exhibit the behaviour defined by clause 5.15.1. Figure 6.33.3.1‑1 shows the Retrieve Context Source Identity Information interaction and Table 6.33.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.33.3.1-1: Retrieve Context Source Identity Information

-
-
-

Table 6.33.3.1-1: Retrieve Context Source Identity Information request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-ContextSourceIdentity -
-1 -
-200 No Content -
-A response body containing the JSON-LD representation of the Context Source Identity Information. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Context Sources to indicate that retrieval of the Context Source information is unsupported see clause 5.15.1.4. -
-

6.34 Resource: entityMaps

-

6.34.1 Description

-

This resource represents the Entity maps in an NGSI-LD system.

-

6.34.2 Resource definition

-

Resource URI:

-
- -
-

6.34.3 Resource methods

-

6.34.3.1 GET

-

This method is associated to the operation “Create EntityMap for Query Entities” and shall exhibit the behaviour defined by clause 5.14.4, providing an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Create EntityMap for Query Entities” operations via POST is defined in clause 6.34.3.2. Figure 6.34.3.1‑1 shows the Create EntityMap for Query Entities interaction.

-
-

-
-
-

Figure 6.34.3.1-1: Create EntityMap for Query Entities interaction

-
-

The URL parameters that shall be supported by implementations are the same as those for Query Entities and can be found in Table 6.4.3.2‑1. Table 6.34.3.1‑1 describes the request body and possible responses.

-
-

Table 6.34.3.1-1: Create EntityMap for Query Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-N/A -
-N/A -
-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-
-EntityMap -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7. -
-
-

6.34.3.2 POST

-

This method is associated to the operation “Create EntityMap for Query Entities” and shall exhibit the behaviour defined by clause 5.14.4. Figure 6.34.3.2‑1 shows the operation interaction and Table 6.34.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.34.3.2-1: Create EntityMap for Query Entities via POST interaction

-
-
-

Table 6.34.3.2-1: Create EntityMap for Query Entities via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.35 Resource: temporal/entityMaps

-

6.35.1 Description

-

This resource is used for creating entityMaps based on temporal queries in an NGSI-LD system.

-

6.35.2 Resource definition

-

Resource URI:

-
- -
-

6.35.3 Resource methods

-

6.35.3.1 GET

-

This method is associated to the operation “Create EntityMap for Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.14.5, an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Create EntityMap for Query Temporal Evolution of Entities” operations via POST is defined in clause 6.35.3.2. Figure 6.35.3.1‑1 shows this interaction.

-
-

-
-
-

Figure 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities interaction

-
-

The URL parameters that shall be supported by implementations are the same as those for Query Temporal Evolution of Entities and can be found in Table 6.18.3.2‑1. Table 6.35.3.1‑1 describes the request body and possible responses.

-
-

Table 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.35.3.2 POST

-

This method is associated to the operation “Create EntityMap for Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.14.5. Figure 6.35.3.2‑1 shows the operation interaction and Table 6.35.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST interaction

-
-
-

Table 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.36 Resource: snapshots

-

6.36.1 Description

-

This resource represents Snapshots available in an NGSI-LD system.

-

6.36.2 Resource definition

-

Resource URI:

-
- -
-

6.36.3 Resource methods

-

6.36.3.1 POST

-

This method is associated to the operation “Create Snapshot” and shall exhibit the behaviour defined by clause 5.16.1. Figure 6.36.3.1‑1 shows the operation interaction and Table 6.36.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.36.3.1-1: Create Snapshot interaction

-
-
-

Table 6.36.3.1-1: Create Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents parameters for the snapshot to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created snapshot. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that a Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.36.3.2 DELETE

-

This method is associated to the operation “Purge Snapshots” and shall exhibit the behaviour defined by clause 5.16.7. Figure 6.36.3.2‑1 shows the Purge Snapshot interaction.

-
-

-
-
-

Figure 6.36.3.2-1: Purge Snapshots interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.36.3.2‑1 and Table 6.36.3.2-2 describes the request body and possible responses.

-
-

Table 6.36.3.2-1: Purge Snapshots URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
NameData TypeCardinalityRemarks

{TAL}

-

q

{TAL}

-

String

{TAL}

-

1

{TAL}

-

Query as per clause 4.9, restricted to members of the Snapshot data type.

-
-

Table 6.36.3.2-2: Purge Snapshots request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-If some or all of the Snapshots have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully deleted Snapshots, while the second array (errors) contains information about the error for each of the Snapshots that could not be deleted. There is no restriction as to the order of the Snapshots IDs in the arrays. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a filter not matching any Snapshots, see clause 6.3.2. -
-

6.37 Resource: snapshots/{snapshotId}

-

6.37.1 Description

-

This resource represents a snapshot in an NGSI-LD system.

-

6.37.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.37.2‑1.

-
-

Table 6.37.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-snapshotId -
-Id (URI) of the Snapshot whose status is to be retrieved or updated, or the Snapshot to be deleted. -
-

6.37.3 Resource methods

-

6.37.3.1 GET

-

This method is associated to the operation “Retrieve Snapshot Status” and shall exhibit the behaviour defined by clause 5.16.3. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.1‑1 shows the Retrieve Snapshot Status interaction and Table 6.37.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.1-1: Retrieve Snapshot Status interaction

-
-
-

Table 6.37.3.1-1: Retrieve Snapshot Status request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-Response Body -
-Data Type -
-Cardinality -
-Response Codes -
-Remarks -
-Snapshot -
-1 -
-200 OK -
-

A response body containing the JSON-LD representation of the target Snapshot status.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

404 Not Found

-
-

It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

-
-

6.37.3.2 PATCH

-

This method is associated to the operation “Update Snapshot Status” and shall exhibit the behaviour defined by clause 5.16.4. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.2‑1 shows the Update Snapshot Status interaction and Table 6.37.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.2-1: Update Snapshot Status interaction

-
-
-

Table 6.37.3.2-1: Update Snapshot Status request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the Snapshot fragment with which the Snapshot status is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Snapshot -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the updated Snapshot status. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2. -
-

6.37.3.3 DELETE

-

This method is associated to the operation “Delete Snapshot” and shall exhibit the behaviour defined by clause 5.16.5. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.3‑1 shows the Delete Snapshot interaction and Table 6.37.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.3-1: Delete Snapshot interaction

-
-
-

Table 6.37.3.3-1: Delete Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a snapshot identifier not known to the system, see clause 6.3.2. -
-

6.38 Resource: snapshots/{snapshotId}/clone

-

6.38.1 Description

-

This resource enables the cloning of a snapshot in an NGSI-LD system.

-

6.38.2 Resource definition

-

Resource URI:

-
- -
-

Resource URI variables for this resource are defined in Table 6.38.2‑1.

-
-

Table 6.38.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-snapshotId -
-Id (URI) of the Snapshot to be queried or deleted. -
-

6.38.3 Resource methods

-

6.38.3.1 POST

-

This method is associated to the operation “Clone Snapshot” and shall exhibit the behaviour defined by clause 5.16.2. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.38.3.1‑1 shows the Clone Snapshot interaction and Table 6.38.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.38.3.1-1: Clone Snapshot interaction

-
-
-

Table 6.38.3.1-1: Clone Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents parameters for the cloned snapshot.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the cloned snapshot. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a Snapshot identifier (URI) not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
- - diff --git a/API-html/12-tabapi-mqtt-notification-binding.html b/API-html/12-tabapi-mqtt-notification-binding.html deleted file mode 100644 index 8be86ecfb08a6aee3aca1628e410406e597d0741..0000000000000000000000000000000000000000 --- a/API-html/12-tabapi-mqtt-notification-binding.html +++ /dev/null @@ -1,1564 +0,0 @@ - - - - - - - -7 API MQTT Notification Binding - - - - - - - - -

7 API MQTT Notification Binding

-

7.1 Introduction

-

This clause defines the optional support of the NGSI-LD API for sending notifications via the MQTT protocol [24] and [25]. The subscriptions are handled using the HTTP binding as described in clause 6, but instead of an HTTP endpoint, an MQTT endpoint is provided.

-

7.2 Notification behaviour

-

In case a subscription received via HTTP specifies an MQTT endpoint in the “notification.endpoint.uri” member of the subscription structure (defined by clauses 5.2.12, 5.2.14 and 5.2.15), and the MQTT notification binding is supported by the NGSI-LD implementation, notifications related to this subscription shall be sent via the MQTT protocol.

-

The syntax of an MQTT endpoint URI is mqtt[s]://[<username>][:<password>]@<host>[:<port>]/<topic>[/<subtopic>]* and follows an existing convention for representing an MQTT endpoint as a URI [i.19].

-

Username and password can be optionally specified as part of the endpoint URI. If the port is not explicitly specified, the default MQTT port is 1883 for MQTT over TCP and 8883 for mqtts, i.e. Secure MQTT over TLS. MQTT supports the structuring of topics as a hierarchy with any number of subtopic levels, which can be specified as part of the endpoint URI.

-

In MQTT, all non-protocol information has to be included into the MQTT message. This means that the actual notification as specified in clause 5.3.1, as well as additional information like MIME type, possibly the link to the @context and additional user-specified information, which in the HTTP case is provided as headers, has to be included into the MQTT message. The MQTT notification message shall be provided as a JSON Object with the two elements “metadata” and “body”. The actual notification, as specified in clause 5.3.1 is the value of “body”, whereas any additional information is provided as key-value pairs in “metadata”.

-

For the MQTT protocol, there are currently two versions supported, MQTTv3.1.1 [24] and MQTTv5.0 [25]. Also, there are three levels of quality of service:

-
- -
-

These can be specified in the subscription as part of the optional array of KeyValuePair type (defined by clause 5.2.22) “notification.endpoint.notifierInfo”. The MQTT protocol parameters can be found in Table 7.2‑1. If not present, the given default value is used.

-
-

Table 7.2-1: Protocol parameters for MQTT in notifierInfo

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Key -
-Possible Values -
-Default -
-Source -
-Description -
-MQTT-QoS -
-0, 1, 2 -
-0 -
-

Subscription’s notification.endpoint

-

.notifierInfo

-
-MQTT Quality of service, at most once (0), at least once (1) and exactly once (2) -
-MQTT-Version -
-mqtt3.1.1, mqtt5.0 -
-mqtt5.0 -
-

Subscription’s notification.endpoint

-

.notifierInfo

-
-Version of MQTT protocol -
-

The MIME type associated with the notification shall be “application/json” by default. However, this can be changed to”application/ld+json” by means of the “endpoint.accept” member. The MIME type is specified as Content-Type in the “metadata” element of the MQTT message. If the target MIME type is “application/json” then the reference to the JSON-LD @context is provided as Link in the “metadata” element of the MQTT message, following the specification of the HTTP Link header as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available). Table 7.2‑2 lists these “receiver side” metadata parameters.

-
-

Table 7.2-2: Parameters for MQTT in “metadata”

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Key -
-Possible Values -
-Default -
-Source -
-Description -
-Content-Type -
-“application/json”, “application/ld+json” -
-“application/json” -
-

Subscription’s

-

notification

-

.endpoint.accept

-
-MIME type of the notification included in the “body” element of the MQTT message -
-Link -
-Same format as specified in JSON-LD specification [2], section 6.2 for the HTTP Link header -
-Link Header provided in Subscription -
-Contains the reference to the @context in case Content-Type is “application/json”. Example: <http://myhost.org/mycontext>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json” -
-
-

Additionally, if the optional array of KeyValuePair type (defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new entry for each member named “key” of the key, value pairs that make up the array shall be generated and added to the “metadata” element of the MQTT message. The content of each entry shall be set equal to the content of the corresponding “value” member of the KeyValuePair.

- - diff --git a/API-html/13-annex-a-normative-ngsi-ld-identifier-considerations.html b/API-html/13-annex-a-normative-ngsi-ld-identifier-considerations.html deleted file mode 100644 index 30f445415ad2ea7a8d3f57d55c04b4493b759f2b..0000000000000000000000000000000000000000 --- a/API-html/13-annex-a-normative-ngsi-ld-identifier-considerations.html +++ /dev/null @@ -1,1435 +0,0 @@ - - - - - - - -Annex A (normative): NGSI-LD identifier considerations - - - - - - - - -

Annex A (normative): NGSI-LD identifier considerations

-

A.1 Introduction

-

The purpose of identifiers is to allow uniquely identifying NGSI-LD elements (Entities, Context Subscriptions or Context Source Registrations) within an NGSI-LD system. This annex is intended to clarify the different issues around the design of identifiers in NGSI-LD.

-

A.2 Entity identifiers

-

In order to enable the participation of NGSI-LD in linked data scenarios, all Entities are identified by URIs. If those URIs are expected to participate in external linked data relationships they should be dereferenceable.

-

It is noteworthy that the identifier from the point of view of NGSI-LD is different from the inherent identifier that a specific Entity may have. For instance, an NGSI-LD Entity of Type ”Vehicle” may have a Property named licencePlateNumber, which it is actually a unique identifier from the point of view of the Entity domain, as it uniquely identifies the specific vehicle instance. However, from the point of view of the NGSI-LD system, it may have another identifier which might or might not include such licence plate number identifier.

-

A.3 NGSI-LD namespace

-

NGSI-LD defines a specific URN [9] namespace intended to help API users to design readable, clean and simple identifiers. As it is based on URNs, the usage of this identification approach is not recommended when dereferenceable URIs are needed (fully-fledged linked data scenarios).

-

The referred namespace is defined as follows (to be registered with IANA):

-
- -
-

EntityTypeName shall be an Entity Type name which can be expanded to a URI as per the @context.

-

EntityIdentificationString shall be a string that allows uniquely identifying the subject Entity in combination with the other items being part of the NSS.

-
-
-

EXAMPLE:

-
-
-

urn:ngsi-ld:Person:28976543 .

-
-
-

It is recommended that applications use this URN namespace when applicable.

-

In general, the URN specification defines namespace equivalence in a case-insensitive manner, however it is assumed that context-broker implementations shall always use lowercase letters in namespaces where they have a choice in case, unless there is a strong reason otherwise. Restricting the namespace prefix to lower case urn:ngsi-ld: can improve caching and retrieval, since this ensures since alphabetic characters within the namespace specific string are always consistent.

- - diff --git a/API-html/14-annex-b-normative-core-ngsi-ld-context-definition.html b/API-html/14-annex-b-normative-core-ngsi-ld-context-definition.html deleted file mode 100644 index 3b2efb81a7566b1bc283925b6ad2b3af785876f1..0000000000000000000000000000000000000000 --- a/API-html/14-annex-b-normative-core-ngsi-ld-context-definition.html +++ /dev/null @@ -1,1923 +0,0 @@ - - - - - - - -Annex B (normative): Core NGSI-LD @context definition - - - - - - - - -

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

-

Below is the definition of the Core NGSI-LD @context which shall be supported by implementations.

-

Such definition has been tested using [i.7].

-
{
-  "@context": {
-    "@version": 1.1,
-    "@protected": true,
-    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
-    "geojson": "https://purl.org/geojson/vocab#",
-    "id": "@id",
-    "type": "@type",
-    "Attribute": "ngsi-ld:Attribute",
-    "AttributeList": "ngsi-ld:AttributeList",
-    "ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity",
-    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification",
-    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration",
-    "Date": "ngsi-ld:Date",
-    "DateTime": "ngsi-ld:DateTime",
-    "EntityType": "ngsi-ld:EntityType",
-    "EntityTypeInfo": "ngsi-ld:EntityTypeInfo",
-    "EntityTypeList": "ngsi-ld:EntityTypeList",
-    "ExecutionResultDetails": "ngsi-ld:ExecutionResultDetails",
-    "Feature": "geojson:Feature",
-    "FeatureCollection": "geojson:FeatureCollection",
-    "GeoProperty": "ngsi-ld:GeoProperty",
-    "GeometryCollection": "geojson:GeometryCollection",
-    "JsonProperty": "ngsi-ld:JsonProperty",
-    "LanguageProperty": "ngsi-ld:LanguageProperty",
-    "LineString": "geojson:LineString",
-    "ListProperty": "ngsi-ld:ListProperty",
-    "ListRelationship": "ngsi-ld:ListRelationship",
-    "MultiLineString": "geojson:MultiLineString",
-    "MultiPoint": "geojson:MultiPoint",
-    "MultiPolygon": "geojson:MultiPolygon",
-    "Notification": "ngsi-ld:Notification",
-    "Point": "geojson:Point",
-    "Polygon": "geojson:Polygon",
-    "Property": "ngsi-ld:Property",
-    "Relationship": "ngsi-ld:Relationship",
-    "Snapshot": "ngsi-ld:Snapshot",
-    "SnapshotNotification": "ngsi-ld:SnapshotNotification",
-    "Subscription": "ngsi-ld:Subscription",
-    "TemporalProperty": "ngsi-ld:TemporalProperty",
-    "Time": "ngsi-ld:Time",
-    "VocabProperty": "ngsi-ld:VocabProperty",
-    "accept": "ngsi-ld:accept",
-    "aggrParams": "ngsi-ld:aggrParams",
-    "aggrMethods": "ngsi-ld:aggrMethods",
-    "aggrPeriodDuration": "ngsi-ld:aggrPeriodDuration",
-    "attributeCount": "attributeCount",
-    "attributeDetails": "attributeDetails",
-    "attributeList": {
-      "@id": "ngsi-ld:attributeList",
-      "@type": "@vocab"
-    },
-    "attributeName": {
-      "@id": "ngsi-ld:attributeName",
-      "@type": "@vocab"
-    },
-    "attributeNames": {
-      "@id": "ngsi-ld:attributeNames",
-      "@type": "@vocab"
-    },
-    "attributeTypes": {
-      "@id": "ngsi-ld:attributeTypes",
-      "@type": "@vocab"
-    },
-    "attributes": {
-      "@id": "ngsi-ld:attributes",
-      "@type": "@vocab"
-    },
-    "attrs": "ngsi-ld:attrs",
-    "avg": {
-      "@id": "ngsi-ld:avg",
-      "@container": "@list"
-    },
-    "bbox": {
-      "@container": "@list",
-      "@id": "geojson:bbox"
-    },
-    "cacheDuration": "ngsi-ld:cacheDuration",
-    "collation": "ngsi-ld:collation",
-    "containedBy": "ngsi-ld:isContainedBy",
-    "contextSourceAlias": "ngsi-ld:contextSourceAlias",
-    "contextSourceExtras": {
-      "@id": "ngsi-ld:contextSourceExtras",
-      "@type": "@json"
-    },
-    "contextSourceInfo": "ngsi-ld:contextSourceInfo",
-    "contextSourceTimeAt": {
-      "@id": "ngsi-ld:contextSourceTimeAt",
-      "@type": "DateTime"
-    }, 
-    "contextSourceUptime": "ngsi-ld:contextSourceUptime",
-    "cooldown": "ngsi-ld:cooldown",
-    "coordinates": {
-      "@container": "@list",
-      "@id": "geojson:coordinates"
-    },
-    "createdAt": {
-      "@id": "ngsi-ld:createdAt",
-      "@type": "DateTime"
-    },
-    "csf": "ngsi-ld:csf",
-"data": "ngsi-ld:data",
-"dataset": {
-"@id": "ngsi-ld:hasDataset",
-      "@container": "@index"
-},
-"datasetId": {
-"@id": "ngsi-ld:datasetId",
-"@type": "@id"
-    },
-    "deletedAt": {
-      "@id": "ngsi-ld:deletedAt",
-      "@type": "DateTime"
-    }, 
-    "description": "http://purl.org/dc/terms/description",
-    "detail": "ngsi-ld:detail",
-    "distinctCount": {
-      "@id": "ngsi-ld:distinctCount",
-      "@container": "@list"
-    },
-    "endAt": {
-      "@id": "ngsi-ld:endAt",
-      "@type": "DateTime"
-    },
-    "endTimeAt": {
-      "@id": "ngsi-ld:endTimeAt",
-      "@type": "DateTime"
-    },
-    "endpoint": "ngsi-ld:endpoint",
-    "entities": "ngsi-ld:entities",
-    "entity": "ngsi-ld:entity",
-    "entityCount": "ngsi-ld:entityCount",
-    "entityId": {
-      "@id": "ngsi-ld:entityId",
-      "@type": "@id"
-    },
-    "entityList": {
-      "@id": "ngsi-ld:entityList",
-      "@container": "@list"
-    },
-    "entityMap": "ngsi-ld:hasEntityMap",
-    "error": "ngsi-ld:error",
-    "errors": "ngsi-ld:errors",
-    "expandValues": "ngsi-ld:expandValues",
-    "expiresAt": {
-      "@id": "ngsi-ld:expiresAt",
-      "@type": "DateTime"
-    },
-    "features": {
-      "@container": "@set",
-      "@id": "geojson:features"
-    },
-    "format": "ngsi-ld:format",
-    "geoQ": "ngsi-ld:geoQ",
-    "geometry": "geojson:geometry",
-    "geoproperty": "ngsi-ld:geoproperty",
-    "georel": "ngsi-ld:georel",
-    "idPattern": "ngsi-ld:idPattern",
-    "information": "ngsi-ld:information",
-    "instanceId": {
-      "@id": "ngsi-ld:instanceId",
-      "@type": "@id"
-    },
-    "isActive": "ngsi-ld:isActive",
-    "join": "ngsi-ld:join",
-    "joinLevel": "ngsi-ld:hasJoinLevel",
-    "json": {
-      "@id": "ngsi-ld:hasJSON", "@type": "@json"
-    },
-    "jsonKeys": "ngsi-ld:jsonKeys",
-    "jsons": {
-      "@id": "ngsi-ld:jsons",
-      "@container": "@list"
-    },
-    "key": "ngsi-ld:hasKey",
-    "lang": "ngsi-ld:lang",
-    "languageMap": {
-      "@id": "ngsi-ld:hasLanguageMap",
-      "@container": "@language"
-    },
-    "languageMaps": {
-      "@id": "ngsi-ld:hasLanguageMaps",
-      "@container": "@list"
-    },
-    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
-    "lastFailure": {
-      "@id": "ngsi-ld:lastFailure",
-      "@type": "DateTime"
-    },
-    "lastNotification": {
-      "@id": "ngsi-ld:lastNotification",
-      "@type": "DateTime"
-    },
-    "lastSuccess": {
-      "@id": "ngsi-ld:lastSuccess",
-      "@type": "DateTime"
-    },
-    "lastUsedAt": {
-      "@id": "ngsi-ld:lastUsedAt",
-      "@type": "DateTime"
-    },
-    "linkedMaps": "ngsi-ld:linkedMaps",
-    "localOnly": "ngsi-ld:localOnly",
-    "location": "ngsi-ld:location",
-    "management": "ngsi-ld:management",
-    "managementInterval": "ngsi-ld:managementInterval",
-    "max": {
-      "@id": "ngsi-ld:max",
-      "@container": "@list"
-    },
-    "min": {
-      "@id": "ngsi-ld:min",
-      "@container": "@list"
-    },
-    "mode": "ngsi-ld:mode",
-    "modifiedAt": {
-      "@id": "ngsi-ld:modifiedAt",
-      "@type": "DateTime"
-    },
-    "ngsildproof": {
-      "@id": "ngsi-ld:ngsildproof",
-      "@context": [{
-        "entityIdSealed": "ngsi-ld:entityIdSealed",
-        "entityTypeSealed": {
-          "@id": "ngsi-ld:entityTypeSealed",
-          "@type": "@vocab"
-        }
-      },
-      "https://w3id.org/security/data-integrity/v2"
-      ]
-    },
-    "notification": "ngsi-ld:notification",
-    "notificationTrigger": "ngsi-ld:notificationTrigger",
-    "notifiedAt": {
-      "@id": "ngsi-ld:notifiedAt",
-      "@type": "DateTime"
-    },
-    "notifierInfo": "ngsi-ld:notifierInfo",
-    "notUpdated": "ngsi-ld:notUpdated",
-    "object": {
-      "@id": "ngsi-ld:hasObject",
-      "@type": "@id"
-    },
-    "objectList": {
-      "@id": "ngsi-ld:hasObjectList",
-      "@container": "@list"
-    },
-    "objectLists": {
-      "@id": "ngsi-ld:hasObjectLists",
-      "@container": "@list"
-    },
-    "objects": {
-      "@id": "ngsi-ld:hasObjects",
-      "@container": "@list"
-    },
-    "objectType": {
-      "@id": "ngsi-ld:hasObjectType",
-      "@type": "@vocab"
-    },
-    "observationInterval": "ngsi-ld:observationInterval",
-    "observationSpace": "ngsi-ld:observationSpace",
-    "observedAt": {
-      "@id": "ngsi-ld:observedAt",
-      "@type": "DateTime"
-    },
-    "omit": "ngsi-ld:omit",
-    "operations": "ngsi-ld:operations",
-    "operationSpace": "ngsi-ld:operationSpace",
-    "orderBy": {
-      "@container": "@list",
-      "@id": "ngsi-ld:orderBy"
-    },
-    "ordering": "ngsi-ld:ordering",
-    "pick": "ngsi-ld:pick",
-    "previousJson": {
-      "@id": "ngsi-ld:hasPreviousJson",
-      "@type": "@json"
-    },
-    "previousLanguageMap": {
-      "@id": "ngsi-ld:hasPreviousLanguageMap",
-      "@container": "@language"
-    },
-    "previousObject": {
-      "@id": "ngsi-ld:hasPreviousObject",
-      "@type": "@id"
-    },
-    "previousObjectList": {
-      "@id": "ngsi-ld:hasPreviousObjectList",
-      "@container": "@list"
-    },
-    "previousValue": "ngsi-ld:hasPreviousValue",
-    "previousValueList": {
-      "@id": "ngsi-ld:hasPreviousValueList",
-      "@container": "@list"
-    },
-    "previousVocab": {
-      "@id": "ngsi-ld:hasPreviousVocab",
-      "@type": "@vocab"
-    },
-    "problemDetails": {
-      "@id": "ngsi-ld:problemDetails",
-      "@type": "@json"
-    },
-    "properties": "geojson:properties",
-    "propertyNames": {
-      "@id": "ngsi-ld:propertyNames",
-      "@type": "@vocab"
-    },
-    "q": "ngsi-ld:q",
-    "reason": "ngsi-ld:reason",
-    "receiverInfo": "ngsi-ld:receiverInfo",
-    "refreshRate": "ngsi-ld:refreshRate",
-    "registrationId": "ngsi-ld:registrationId",
-    "registrationName": "ngsi-ld:registrationName",
-    "relationshipNames": {
-      "@id": "ngsi-ld:relationshipNames",
-      "@type": "@vocab"
-},
-    "resultStatus": "ngsi-ld:resultStatus",
-"scope": "ngsi-ld:scope",
-"scopeQ": "ngsi-ld:scopeQ",
-"showChanges": "ngsi-ld:showChanges",
-    "snapshotId": "ngsi-ld:snapshotId",
-    "snapshotLifetime": "ngsi-ld:snapshotLifetime",
-    "snapshotPriority": "ngsi-ld:snapshotPriority",
-    "snapshotQueries": {
-      "@id": "ngsi-ld:snapshotQueries",
-      "@container": "@list"
-    },
-    "snapshotQueriesDetails": {
-      "@id": "ngsi-ld:snapshotQueriesDetails",
-      "@container": "@list"
-    },
-    "snapshotStatus": "ngsi-ld:snapshotStatus",
-    "snapshotTemporalQueries": {
-      "@id": "ngsi-ld:snapshotTemporalQueries",
-      "@container": "@list"
-    },
-    "snapshotTemporalQueriesDetails": {
-      "@id": "ngsi-ld:snapshotTemporalQueriesDetails",
-      "@container": "@list"
-    },
-    "startAt": {
-      "@id": "ngsi-ld:startAt",
-      "@type": "DateTime"
-    },
-    "status": "ngsi-ld:status",
-    "stddev": {
-      "@id": "ngsi-ld:stddev",
-      "@container": "@list"
-    },
-    "subscriptionId": {
-      "@id": "ngsi-ld:subscriptionId",
-      "@type": "@id"
-    },
-    "subscriptionName": "ngsi-ld:subscriptionName",
-    "success": {
-      "@id": "ngsi-ld:success",
-      "@type": "@id"
-    },
-    "sum": {
-      "@id": "ngsi-ld:sum",
-      "@container": "@list"
-    },
-    "sumsq": {
-      "@id": "ngsi-ld:sumsq",
-      "@container": "@list"
-    },
-    "sysAttrs": "ngsi-ld:sysAttrs",
-    "temporalQ": "ngsi-ld:temporalQ",
-    "tenant": {
-      "@id": "ngsi-ld:tenant",
-      "@type": "@id"
-    },
-    "throttling": "ngsi-ld:throttling",
-    "timeAt": {
-      "@id": "ngsi-ld:timeAt",
-      "@type": "DateTime"
-    },
-    "timeInterval": "ngsi-ld:timeInterval",
-    "timeout": "ngsi-ld:timeout",
-    "timeproperty": "ngsi-ld:timeproperty",
-    "timerel": "ngsi-ld:timerel",
-    "timesFailed": "ngsi-ld:timesFailed",
-    "timesSent": "ngsi-ld:timesSent",
-    "title": "http://purl.org/dc/terms/title",
-    "totalCount": {
-      "@id": "ngsi-ld:totalCount",
-      "@container": "@list"
-    },
-    "triggerReason": "ngsi-ld:triggerReason",
-    "typeList": {
-      "@id": "ngsi-ld:typeList",
-      "@type": "@vocab"
-    },
-    "typeName": {
-      "@id": "ngsi-ld:typeName",
-      "@type": "@vocab"
-    },
-    "typeNames": {
-      "@id": "ngsi-ld:typeNames",
-      "@type": "@vocab"
-    },
-    "unchanged": "ngsi-ld:unchanged",
-    "unitCode": "ngsi-ld:unitCode",
-    "updated": "ngsi-ld:updated",
-    "uri": "ngsi-ld:uri",
-    "value": "ngsi-ld:hasValue",
-    "valueList": {
-      "@id": "ngsi-ld:hasValueList",
-      "@container": "@list"
-    },
-    "valueLists": {
-      "@id": "ngsi-ld:hasValueLists",
-      "@container": "@list"
-    },
-    "values": {
-      "@id": "ngsi-ld:hasValues",
-      "@container": "@list"
-    },
-    "valueType": {
-      "@id": "ngsi-ld:hasValueType",
-      "@type": "@vocab"
-    },
-    "vocab": {
-      "@id": "ngsi-ld:hasVocab",
-      "@type": "@vocab"
-    },
-    "vocabs": {
-      "@id": "ngsi-ld:hasVocabs",
-      "@container": "@list"
-    },
-    "watchedAttributes": {
-      "@id": "ngsi-ld:watchedAttributes",
-      "@type": "@vocab"
-    },
-    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/"
-  }
-}
-
-
-

NOTE:

-
-
-

Implementers can take advantage of prefixed terms, i.e. in the form ngsi-ld:term, to provide a terser representation of the Core @context .

-
-
- - diff --git a/API-html/15-annex-c-informative-examples-of-using-the-api.html b/API-html/15-annex-c-informative-examples-of-using-the-api.html deleted file mode 100644 index 5ee7e82ba389d1afcd77c61d163815d7d5b0e93f..0000000000000000000000000000000000000000 --- a/API-html/15-annex-c-informative-examples-of-using-the-api.html +++ /dev/null @@ -1,4264 +0,0 @@ - - - - - - - -Annex C (informative): Examples of using the API - - - - - - - - -

Annex C (informative): Examples of using the API

-

C.1 Introduction

-

This annex is informative and is intended to show in action the JSON-LD representation defined by NGSI-LD.

-

JSON representations of the examples shown in this annex can be found at [i.15].

-

C.2 Entity Representation

-

C.2.1 Property Graph

-

Figure C.2.1‑1 shows a diagram representing a property graph to be used for the examples discussed in this clause.

-
-

-
-
-

Figure C.2.1-1: Reference example

-
-

As per the algorithms described above and as per the rules for generating the JSON-LD representation of NGSI-LD entities the above graph will result in the following JSON-LD representations. The syntax has been checked using the JSON-LD Playground tool [i.5].

-

C.2.2 Vehicle Entity

-

Normalized Representation

-

The normalized representation is a lossless representation of an Entity, where every Property is defined by a type and a value and every Relationship is defined by a type and an object.

-

Below there is a representation of an Entity of Type “Vehicle”. It can be observed that the @context is composed of different parts, namely the Core @context and several vocabulary-specific @contexts.

-

It is noteworthy that the @context corresponding to the Parking domain is included as it is referenced through the isParked Relationship.

-

Normalized Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned in an expanded format. Attributes of type“Relationship”are returned with an additional entity sub-Attribute, which holds the normalized Linked Entity data corresponding to the Relationship’s target object URI. Attributes of type“ListRelationship” are returned with an additional entityList sub-Attribute which in turn holds an ordered array of the normalized Linked Entities corresponding to the target “objectList” URIs.

-

Normalized Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of normalized Entities is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional normalized Linked Entity holding data corresponding to the Relationship’s target object URI is appended to the array. For Attributes of type “ListRelationship”, an array of normalized Linked Entities is appended, which hold the data corresponding to each of the target URIs found within its objectList.

-

[

-

Normalized Representation when Language Filter is used

-

When the Language Filter (see clause 4.15) is used, Properties of type “LanguageProperty” are returned as type “Property”, and their languageMaps are reduced to simple strings. For example if the language filter lang=fr is specified, only the value for French language is present.

-
{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-        "type": "Relationship",
-    "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-    "type": "Relationship",
-    "objectType": "OffStreetParking",
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "entity": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "value": "Top Parking",
-    "type": "Property"
-    },
-    "operatedBy": {
-    "object" "urn:ngsi-ld:Company:BigParkingCorp",
-    "type": "Relationship"
-    },
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person", 
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "entity": [
-    {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": {
-        "value": "Alice",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": {
-        "value": "Bob",
-        "type": "Property"
-    }
-    }
-    ]
-},
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ],
-    "entityList": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": {
-        "value": "Antwerp",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": {
-        "value": "Rotterdam",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": {
-        "value": "Amsterdam",
-        "type": "Property"
-    }
-    }
-    ]
-},
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-    {
-        "id": "urn:ngsi-ld:Vehicle:A4567",
-        "type": "Vehicle",
-        "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-        "type": "Relationship",
-    "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-        "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-    "tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120,�[�6],
-        "valueType": "Integer"
-    "unitCode": "MMT"
-    },
-    "passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-    "route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-        {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-        {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "value": "Top Parking",
-    "type": "Property"
-    },
-    "operatedBy": {
-    "object": "urn:ngsi-ld:Company:BigParkingCorp",
-    "type": "Relationship"
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": {
-    "value": "Alice",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": {
-    "value": "Bob",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": {
-    "value": "Antwerp",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": {
-    "value": "Rotterdam",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": {
-    "value": "Amsterdam",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    }
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "Property",
-    "value": "Grand Place",
-    "lang": "fr"
-    },
-    "isParked": {
-        "type": "Relationship",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-},
-"@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-

Concise Representation

-

The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute type members are omitted and the following rules are applied:

-
- -
-

Concise Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned in an expanded format. The concise Linked Entity data corresponding to the Relationship’s target object URI is returned within an entity sub-Attribute. Attributes of type “ListRelationship”are returned within an entityList sub-Attribute which in turn holds an ordered array of the Linked Entities in the concise format corresponding to each of the targetobjectList URIs.

-

“name”: “ Antwerp”

-

“name”: “Rotterdam

-

“name”: “Amsterdam”

-

Concise Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of concise Entities is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional concise Linked Entity holding data corresponding to the Relationship’s target object URI is appended to the response. For Attributes of type “ListRelationship”, an array of concise Linked Entities is appended to the response which hold the data corresponding to each of the target URIs found within its objectList.

-

[

-

Concise representation when Language Filter is used

-

The rules apply as defined in the previous examples. For example if the language filter lang=fr is specified.

-

Simplified Representation

-

The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

Simplified Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned as a JSON object holding key-value pairs corresponding to the data from the Relationship’s target object URI in simplified format. Attributes of type “ListRelationship”are returned as array of JSON objects each holding key-value pairs corresponding to the data obtained from the target objectList URIs.

-

Simplified Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of JSON Objects is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional JSON Object of key-value pairs holding data corresponding to the Relationship’s target object URI is appended to the response. For Attributes of type “ListRelationship”, an array of JSON Objects each holding key-value pairs corresponding to the data obtained from the target objectList URIs is appended to the response.

-

[

-

Simplified Representation of Natural Language Attributes

-

The simplified natural language representation is a collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph, and where languageMaps are reduced to simple string properties. For example if the language filter lang=fr is specified.

-

Multiple attribute example

-

Below is an example, where the speed of the car is provided by two different sources. As both may be relevant at the same time, there are two individual attribute instances for speed; each is identified by a datasetId and both instances are represented in an array. The datasetId enables individually creating, updating and deleting a particular instance without affecting the instance from another source.

-

Simplified Representation of a multi-attribute

-

The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

C.2.3 Parking Entity

-

Normalized Representation

-

The normalized representation is a lossless representation of an Entity, where every Property is defined by a type and a value and every Relationship is defined by a type and an object.

-

Below there is a representation of an Entity of Type “OffStreetParking”. It can be observed that the @context is composed of two different elements, the Core one and the vocabulary-specific one.

-
{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-        "languageMap": {
-            "fr": "Grand Place",
-            "nl": "Grote Markt"
-        } 
-    },
-    "isParked": {
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer"
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ]
-    },
-"@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-        "languageMap": {
-            "fr": "Grand Place",
-            "nl": "Grote Markt"
-        } 
-    },
-    "isParked": {
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-        "entity": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Top Parking",
-    "operatedBy": {
-    "object": "urn:ngsi-ld:Company:BigParkingCorp"
-      }
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "entity": [
-    {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": "Alice"
-        },
-        {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": "Bob"
-        }
-]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ],
-    "entityList": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    }
-    ]
-},
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-    {
-        "id": "urn:ngsi-ld:Vehicle:A4567",
-        "type": "Vehicle",
-        "brandName": "Mercedes",
-        "street": {
-            "languageMap": {
-                "fr": "Grand Place",
-                "nl": "Grote Markt"
-            } 
-        },
-        "isParked": { 
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-            "observedAt": "2017-07-29T12:00:04Z",
-            "providedBy": {
-                "object": "urn:ngsi-ld:Person:Bob"
-            } 
-        },
-    "category": {
-    "vocab": "non-commercial"
-    },
-    "tyreTreadDepths": {
-    "valueList": [300, 300, 120,�[�6],
-        "valueType": "Integer",
-    "unitCode": "MMT"
-    },
- "passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-    "route": {
-    "objectType": "City",
-    "objectList": [
-        "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-        "urn:ngsi-ld:City:Amsterdam"
-    ]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Top Parking",
-    "operatedBy": {
-    "object" "urn:ngsi-ld:Company:BigParkingCorp",
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": "Alice",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": "Bob",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": " Antwerp",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": "Rotterdam",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": "Amsterdam",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    }
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes"
-    },
-    "street": {
-    "value": "Grand Place",
-    "lang": "fr"
-    },
-    "isParked": {
-  "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120,�[�6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-   "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ]
-},
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    }
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120,�[�6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-"route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    },
-    "isParked": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": " OffStreetParking",  
-    "name": "Top Parking",
-    "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp"
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120,�[�6],
-"passengers": [
- {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person", 
-    "name": "Alice"
-    },
-    {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person", 
-    "name": "Bob"
-    }
-],
-    "route": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": " Antwerp"
-        },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": "Rotterdam
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": "Amsterdam"
-        }
-    ],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    }
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120,�[�6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-},
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": " OffStreetParking",  
-    "name": "Top Parking",
-    "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp"
-},
-{
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person", 
-    "name": "Alice"
-}
-{
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person", 
-    "name": "Bob"
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": " Antwerp"
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": "Rotterdam
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": "Amsterdam"
-}
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": "Grand Place",
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120,�[�6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-"route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "speed": [{
-        "type": "Property",
-    "value": 55,
-    "source": {
-            "type": "Property",
-    "value": "Speedometer"
-    },
-    "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
-    },
-    {
-        "type": "Property",
-    "value": 54.5,
-    "source": {
-            "type": "Property",
-    "value": "GPS"
-    },
-    "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
-    }],
-    "@context": [
-        {
-    "Vehicle": "http://example.org/Vehicle",
-    "speed": "http://example.org/speed",
-        "source": "http://example.org/hasSource"
-        },
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "speed": {
-    "dataset": {
-    "urn:ngsi-ld:Property:speedometerA4567-speed": 55,
-    "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5
-    }
-    },
-    "@context": [
-        {
-    "Vehicle": "http://example.org/Vehicle",
-    "speed": "http://example.org/speed"
-        },
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "type": "Property",
-        "value": "Downtown One"
-    },
-    "availableSpotNumber": {
-        "type": "Property",
-        "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z",
-        "reliability": {
-        "type": "Property",
-        "value": 0.7
-        },
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-        }
-    },
-    "totalSpotNumber": {
-        "type": "Property",
-        "value": 200
-    },
-    "location": {
-    "type": "GeoProperty",
-    "value": {
-    "type": "Point",
-    "coordinates": [-8.5, 41.2]
-    }
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-

Concise Representation

-

The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute type members are omitted and the following rules are applied:

-
- -
-

Simplified representation

-

The Simplified Representation (also known as ”keyValues”) is a lossy, collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

Normalized GeoJSON Representation

-

The normalized GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object as follows:

-

The GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations.

-

Concise GeoJSON Representation

-

The concise GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object as follows:

-

The concise GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations in concise GeoJSON format.

-

Simplified GeoJSON Representation

-

The simplified GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object where the properties represent a collapsed representation of the Entity, which focuses on Property Values and Relationship objects present at the first level of the graph.

-

The simplified GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations in simplified GeoJSON format.

-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffStreetParking",
-  "name": "Downtown One",
-  "availableSpotNumber": {
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z",
-    "reliability": 0.7,
-    "providedBy": {
-      "object": "urn:ngsi-ld:Camera:C1"
-    }
-  },
-  "totalSpotNumber": 200,
-  "location": {
-    "type": "Point",
-    "coordinates": [
-      -8.5,
-      41.2
-    ]
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": 121,
-    "totalSpotNumber": 200,
-    "location": {
-    "type": "Point",
-    "coordinates": [-8.5, 41.2]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": {
-      "type": "Property",
-      "value": "Downtown One"
-    },
-    "availableSpotNumber": {
-      "type": "Property",
-      "value": 121,
-      "observedAt": "2017-07-29T12:05:02Z",
-      "reliability": {
-        "type": "Property",
-        "value": 0.7
-      },
-      "providedBy": {
-        "type": "Relationship",
-        "object": "urn:ngsi-ld:Camera:C1"
-      }
-    },
-    "location": {
-    "type": "GeoProperty",
-    "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-    }
-    },
-    "totalSpotNumber": {
-      "type": "Property",
-      "value": 200
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/parking.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.5, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": {
-          "type": "Property",
-          "value": "Downtown One"
-        },
-        "availableSpotNumber": {
-          "type": "Property",
-          "value": 121,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": {
-            "type": "Property",
-            "value": 0.7
-          },
-          "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-          }
-        },
-        "totalSpotNumber": {
-          "type": "Property",
-          "value": 200
-        },
-    "location": {
-      "type": "GeoProperty",
-      "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-      }
-    }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.51, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": {
-          "type": "Property",
-          "value": "Downtown Two"
-        },
-        "availableSpotNumber": {
-          "type": "Property",
-          "value": 99,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": {
-            "type": "Property",
-            "value": 0.8
-          },
-          "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C2"
-          }
-        },
-        "totalSpotNumber": {
-          "type": "Property",
-          "value": 100
-        },
-    "location": {
-      "type": "GeoProperty",
-      "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-      }
-    }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [
-      -8.51,
-      41.1
-    ]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": {
-      "value": 121,
-      "observedAt": "2017-07-29T12:05:02Z",
-      "reliability": 0.7,
-      "providedBy": {
-        "object": "urn:ngsi-ld:Camera:C1"
-      }
-    },
-    "location": {
-      "type": "Point",
-      "coordinates": [
-        -8.51,
-        41.1
-      ]
-    },
-    "totalSpotNumber": 200,
-    "@context": [
-      "http://example.org/ngsi-ld/latest/parking.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [
-          -8.5,
-          41.1
-        ]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown One",
-        "availableSpotNumber": {
-          "value": 121,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": 0.7,
-          "providedBy": {
-            "object": "urn:ngsi-ld:Camera:C1"
-          }
-        },
-        "totalSpotNumber": 200,
-        "location": {
-          "type": "Point",
-          "coordinates": [
-            -8.51,
-            41.1
-          ]
-        }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [
-          -8.51,
-          41.1
-        ]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown Two",
-        "availableSpotNumber": {
-          "value": 99,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": 0.8,
-          "providedBy": {
-            "object": "urn:ngsi-ld:Camera:C2"
-          }
-        },
-        "totalSpotNumber": 100,
-        "location": {
-          "type": "Point",
-          "coordinates": [
-            -8.51,
-            41.1
-          ]
-        }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:offstreetparking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": 121,
-    "totalSpotNumber": 200,
-    "location": {
-      "type": "Point",
-      "coordinates": [-8.51, 41.1]
-    }
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.5, 41.2]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown One",
-        "availableSpotNumber": 121,
-        "totalSpotNumber": 200,
-        "location": {
-       "type": "Point",
-       "coordinates": [-8.5, 41.2]
-        }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.51, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown Two",
-        "availableSpotNumber": 99,
-        "totalSpotNumber": 100,
-        "location": {
-       "type": "Point",
-       "coordinates": [-8.51, 41.1]
-        }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}  
-

C.2.4 @context

-

The disposition of the @context can be as an inline JSON object, as a dereferenceable URI or as a (multiple) combination of both. In the examples above the @context is provided through several dereferenceable URIs. The resulting @context (obtained by merging the content of the resource referenced by the referred URIs) is shown below.

-
-
-

NOTE 1:

-
-
-

For brevity reasons the @context does not contain the API terms defined by clause 5.2 .

-
-
-
-
-

NOTE 2:

-
-
-

Some extra terms are defined because they will be used in examples later presented.

-
-
-

C.3 Context Source Registration

-

Below there is an example representation of a Context Source Registration. It makes use of the @context formerly described.

-

The Registration is referring to a Temporal Context Source capable of providing temporal information from Entities of type ”Vehicle” and ”OffStreetParking”, meeting certain id requirements. More concretely, it can only provide the referenced Properties and Relationships. Temporal information is provided for the given managementInterval, i.e. related to createdAt and modifiedAt Temporal Properties. The managementInterval is specified as an open interval, so only a starting point is given. In addition, the Registration example covers a particular geographical area.

-

C.4 Context Subscription

-

Below there is an example of a Context Subscription. It makes use of the @context formerly described.

-
{
-    "id": "@id",
-    "type": "@type",
-    "Property": "https://uri.etsi.org/ngsi-ld/Property",
-    "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship",
-    "value": "https://uri.etsi.org/ngsi-ld/hasValue",
-    "object": {
-    "@type": "@id",
-    "@id": "https://uri.etsi.org/ngsi-ld/hasObject"
-    },
-    "observedAt": {
-    "@type": "https://uri.etsi.org/ngsi-ld/DateTime",
-    "@id": "https://uri.etsi.org/ngsi-ld/observedAt"
-},
-    "datasetId": {
-        "@id": "https://uri.etsi.org/ngsi-ld/datasetId",
-        "@type":"@id"
-    },
-    "location": "https://uri.etsi.org/ngsi-ld/location",
-"GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty",
-    "Vehicle": "http://example.org/vehicle/Vehicle",
-    "street": "http://example.org/vehicle/street",
-    "brandName": "http://example.org/vehicle/brandName",
-    "category": "http://example.org/vehicle/category",
-    "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths",
-    "passengers": "http://example.org/vehicle/passengers",
-    "speed": "http://example.org/vehicle/speed",
-    "isParked": {
-    "@type": "@id",
-    "@id": "http://example.org/common/isParked"
-    },
-    "OffStreetParking": "http://example.org/parking/OffStreetParking",
-    "availableSpotNumber": "http://example.org/parking/availableSpotNumber",
-    "totalSpotNumber": "http://example.org/parking/totalSpotNumber",
-    "isNextToBuilding": {
-    "@type": "@id",
-    "@id": "http://example.org/common/isNextToBuilding"
-    },
-    "reliability": "http://example.org/common/reliability", 
-    "providedBy": {
-    "@type": "@id",
-    "@id": "http://example.org/common/providedBy"
-    },
-    "name": "http://example.org/common/name",
-"commercial":
-"http://example.org/vehicle/commercial",
-    "non-commercial": "http://example.org/vehicle/non-commercial",
-"Integer": "http://www.w3.org/2001/XMLSchema#Integer
-}
-{ 
-    "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456",
-    "type": "ContextSourceRegistration",
-    "information": [
-   {
-    "entities": [ 
-    {
-                "id": "urn:ngsi-ld:Vehicle:A456",
-    "type": "Vehicle"
-            }
-    ],
-    "propertyNames": ["brandName","speed"],
-    "relationshipNames": ["isParked"]
-   }, 
-   { 
-    "entities": [
-    {
-                "idPattern": ".*downtown$",
-    "type": "OffStreetParking"
-            },
-    {
-                "idPattern": ".*47$",
-    "type": "OffStreetParking"
-            }
-    ],
-    "propertyNames": ["availableSpotNumber","totalSpotNumber"],
-    "relationshipNames": ["isNextToBuilding"]
-      }
-    ],
-    "endpoint": "http://my.csource.org:1026",
-    "location": {
-    "type": "Polygon",
-    "coordinates": [
-             [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0],
-               [100.0, 1.0], [100.0, 0.0]] ]
-    },
-    "managementInterval": {
-    "startAt": " 2017-11-29T14:53:15Z"
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Subscription:mySubscription",
-    "type": "Subscription",
-    "entities": [
-    {
-    "type": "Vehicle"
-        }
-    ],
-    "watchedAttributes": ["speed"],
-    "q": "speed>50",
-    "geoQ": {
-    "georel": "near;maxDistance==2000",
-        "geometry": "Point",
-        "coordinates": [-1,100]
-    },
-    "notification": {
-        "attributes": ["speed"],
-        "format": "keyValues",
-        "endpoint": {
-            "uri": "http://my.endpoint.org/notify",
-            "accept": "application/json"
-        }
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-

The subject of the Context Subscription is Entities of Type Vehicle which speed is greater than 50, and located close to a certain area defined by a reference spatial point. Every time the speed (watched Attribute) of a concerned vehicle, changes, a new notification (including the new speed value) will be received in the specified endpoint.

-

C.5 HTTP REST API Examples

-

C.5.1 Introduction

-

This clause introduces some simple usage examples of the NGSI-LD API (HTTP REST binding). They are not intended to be exhaustive but just a sample for helping readers to understand better the present document. ETSI ISG CIM published a Developer’s Primer with many more examples, see ETSI GR CIM 008 [i.21].

-

C.5.2 Create Entity of Type Vehicle

-

C.5.2.1 HTTP Request

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/ld+json

-
-
-

Content-Length: 556

-
-
-

<Insert Here the JSON-LD representation of a Vehicle as described by [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.html#c.2.2tabvehicle-entity) Vehicle Entity>

-
-

C.5.2.2 HTTP Response

-
-

201 Created

-
-
-

Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567

-
-

C.5.3 Query Entities

-

C.5.3.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” whose brandName attribute is not “Mercedes” . Only give back the brandName attribute and provide the data in the NGSI-LD Simplified Format.

-
-
-

C.5.3.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=Vehicle&q=brandName!=“Mercedes”&format=simplified

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.3.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "brandName": "Volvo",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.4 Query Entities (Pagination)

-

C.5.4.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” . Only give back the brandName attribute and provide the data in the NGSI-LD Simplified Format. Limit the number of entities retrieved to 2.

-
-
-

C.5.4.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type= Vehicle&format=simplified&limit=2

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.4.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
-

Link: </ngsi-ld/v1/entities/?type= Vehicle&format=**simplified**&limit=2&offset=2>; rel=“next”; type=“application/ld+json”

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "brandName": "Volvo",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  },
-  {
-    "id": "urn:ngsi-ld:Vehicle:A456",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.5 Temporal Query

-

C.5.5.1 Introduction

-
-
-

EXAMPLE 1:

-
-
-

Give back the temporal evolution of the attribute speed of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM.

-
-
-
-
-

EXAMPLE 2:

-
-
-

Give back the temporal evolution of the attribute speed and brandName of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM. As brandName attribute does not have any temporal evolution, brandName attribute is omitted in the response.

-
-
-

C.5.5.2 HTTP Request #1

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ ngsi-ld /latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.5.3 HTTP Response #1

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": [
-      {
-        "type": "Property",
-        "value": 120,
-        "observedAt": "2018-08-01T12:03:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 80,
-        "observedAt": "2018-08-01T12:05:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 100,
-        "observedAt": "2018-08-01T12:07:00Z"
-      }
-    ],
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-] 
-

C.5.5.4 HTTP Request #2

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ ngsi-ld /latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.5.5 HTTP Response #2

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": [
-      {
-        "type": "Property",
-        "value": 120,
-        "observedAt": "2018-08-01T12:03:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 80,
-        "observedAt": "2018-08-01T12:05:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 100,
-        "observedAt": "2018-08-01T12:07:00Z"
-      }
-    ],
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.6 Temporal Query (Simplified Representation)

-

C.5.6.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the temporal evolution of the speed attribute for Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM. Simplified representation is required.

-
-
-

C.5.6.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=temporalValues

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.6.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          120,
-          "2018-08-01T12:03:00Z"
-        ],
-        [
-          80,
-          "2018-08-01T12:05:00Z"
-        ],
-        [
-          100,
-          "2018-08-01T12:07:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.7 Retrieve Available Entity Types

-

C.5.7.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all entity types for which entity instances are currently available in the NGSI-LD system.

-
-
-

C.5.7.2 HTTP Request

-
-

GET /ngsi-ld/v1/types

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.7.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:EntityTypeList:34534657",
-  "type": "EntityTypeList",
-  "typeList": [
-    "Vehicle",
-    "OffStreetParking",
-    "http://example.org/parking/ParkingSpot"
-  ]
-}
-
-
-

NOTE:

-
-
-

All entity types that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs).

-
-
-

C.5.8 Retrieve Details of Available Entity Types

-

C.5.8.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of all entity types for which entity instances are currently available in the NGSI-LD system.

-
-
-

C.5.8.2 HTTP Request

-
-

GET /ngsi-ld/v1/types?details=true

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.8.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
[
-  {
-    "id": "http://example.org/vehicle/Vehicle",
-    "type": "EntityType",
-    "typeName": "Vehicle",
-    "attributeNames": [
-      "brandName",
-      "isParked",
-      "location",
-      "speed"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/OffStreetParking",
-    "type": "EntityType",
-    "typeName": "OffStreetParking",
-    "attributeNames": [
-      "availableSpotNumber",
-      "isNextToBuilding",
-      "location",
-      "totalSpotNumber"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/ParkingSpot",
-    "type": "EntityType",
-    "typeName": "http://example.org/parking/ParkingSpot",
-    "attributeNames":[
-      "location",
-      "http://example.org/parking/status"
-    ]
-  }
-] 
-
-
-

NOTE:

-
-
-

The type name of all entity types and all attribute names that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs). The id is always an FQN.

-
-
-

C.5.9 Retrieve Available Entity Type Information

-

C.5.9.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of entity type “Vehicle” (for which entity instances are currently available in the NGSI-LD system).

-
-
-

C.5.9.2 HTTP Request

-
-

GET /ngsi-ld/v1/types/Vehicle

-
-
-

[Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.9.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "http://example.org/vehicle/Vehicle",
-  "type": "EntityTypeInfo",
-  "typeName": "Vehicle",
-  "entityCount": 2,
-  "attributeDetails": [
-    {
-      "id": "http://example.org/vehicle/brandName",
-      "type": "Attribute",
-      "attributeName": "brandName",
-      "attributeTypes": [
-        "Property"
-      ]
-    },
-    {
-      "id": "http://example.org/vehicle/isParked",
-      "type": "Attribute",
-      "attributeName": "isParked",
-      "attributeTypes": [
-        "Relationship"
-      ]
-    },
-    {
-      "id": "https://uri.etsi.org/ngsi-ld/location",
-      "type": "Attribute",
-      "attributeName": "location",
-      "attributeTypes": [
-        "GeoProperty"
-      ]
-    },
-    {
-      "id": "http://example.org/vehicle/speed",
-      "type": "Attribute",
-      "attributeName": "speed",
-      "attributeTypes": [
-        "Property"
-      ]
-    }
-  ]
-}
-

C.5.10 Retrieve Available Attributes

-

C.5.10.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all attribute names for which entity instances are currently available in the NGSI-LD system that have an attribute with the respective name.

-
-
-

C.5.10.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.10.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:AttributeList:56534657",
-  "type": "AttributeList",
-  "attributeList": [
-    "brandName",
-    "isParked",
-    "location",
-    "speed",
-    "http://example.org/parking/status"
-  ]
-}
-
-
-

NOTE:

-
-
-

The attribute names that can be found in the provided @context are given as short names, the others as fully qualified names (FQNs).

-
-
-

C.5.11 Retrieve Details of Available Attributes

-

C.5.11.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of all attributes for which entity instances are currently available in the NGSI-LD system to which an attribute with the respective attribute name belongs.

-
-
-

C.5.11.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes?details=true

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.11.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
[
-  {
-    "id": "http://example.org/vehicle/brandName",
-    "type": "Attribute",
-    "attributeName": "brandName",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "http://example.org/vehicle/isParked",
-    "type": "Attribute",
-    "attributeName": "isParked",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "https://uri.etsi.org/ngsi-ld/location",
-    "type": "Attribute",
-    "attributeName": "location",
-    "typeNames": [
-      "Vehicle",
-      "OffStreetParking",
-      "http://example.org/parking/ParkingSpot"
-    ]
-  },
-  {
-    "id": "http://example.org/vehicle/speed",
-    "type": "Attribute",
-    "attributeName": "speed",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/status",
-    "type": "Attribute",
-    "attributeName": "http://example.org/parking/status",
-    "typeNames": [
-      "http://example.org/parking/ParkingSpot"
-    ]
-  }
-] 
-
-
-

NOTE:

-
-
-

The attribute name and all type names that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs). The id is always an FQN.

-
-
-

C.5.12 Retrieve Available Attribute Information

-

C.5.12.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of the attribute named brandName (for which entity instances with an attribute of this name are currently available in the NGSI-LD system).

-
-
-

C.5.12.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes/brandName

-
-
-

[Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.12.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "http://example.org/vehicle/brandName",
-  "type": "Attribute",
-  "attributeName": "brandName",
-  "attributeTypes": ["Property"],
-  "typeNames": ["Vehicle"],
-  "attributeCount": 2
-}
-

C.5.13 Query Entities (Natural Language Filtering)

-

C.5.13.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” where the marque attribute in British English is “Vauxhall Viva” . Only give back the marque attribute and provide the data in the NGSI-LD Simplified Format and only return language strings in German.

-
-
-

C.5.13.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]== “Vauxhall Viva”&format =simplified&lang=de

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.13.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "marque": "Opel Karl",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.14 Temporal Query (Aggregated Representation)

-

C.5.14.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the maximum and average speed of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM, aggregated by periods of 4 minutes.

-
-
-

C.5.14.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=aggregatedValues

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.14.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": {
-      "type": "Property",
-      "max": [
-        [
-          120,
-          "2018-08-01T12:00:00Z",
-          "2018-08-01T12:04:00Z"
-        ],
-        [
-          100,
-          "2018-08-01T12:04:00Z",
-          "2018-08-01T12:08:00Z"
-        ]
-      ],
-      "avg": [
-        [
-          120,
-          "2018-08-01T12:00:00Z",
-          "2018-08-01T12:04:00Z"
-        ],
-        [
-          90,
-          "2018-08-01T12:04:00Z",
-          "2018-08-01T12:08:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.15 Scope Queries

-

C.5.15.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type ” OffStreetParking” that are within the Scope /Madrid/Centro or /Madrid/Cortes .

-
-
-

C.5.15.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ=“/Madrid/Centro,/Madrid/Cortes”

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.15.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-   {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "OffStreetParking",
-      "scope": "/Madrid/Centro",
-      "name": {
-         "type": "Property",
-         "value": "Downtown One"
-      },
-      "availableSpotNumber": {
-         "type": "Property",
-         "value": 121,
-         "observedAt": "2017-07-29T12:05:02Z",
-         "reliability": {
-            "type": "Property",
-            "value": 0.7
-         },
-         "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-         }
-      },
-      "totalSpotNumber": {
-         "type": "Property",
-         "value": 200
-      },
-      "location": {
-         "type": "GeoProperty",
-         "value": {
-            "type": "Point",
-            "coordinates": [
-               -8.5,
-               41.2
-            ]
-         }
-      },
-      "@context": [
-         "http://example.org/ngsi-ld/latest/parking.jsonld",
-         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-      ]
-   },
-   {
-      "id": "urn:ngsi-ld:OffStreetParking:Corte4",
-      "type": "OffStreetParking",
-      "scope": [
-            "/Madrid/Cortes",
-            "/Company894/UnitC"
-      ],
-      "name": {
-         "type": "Property",
-         "value": "Corte4"
-      },
-      "availableSpotNumber": {
-         "type": "Property",
-         "value": 121,
-         "observedAt": "2017-07-29T12:05:02Z",
-         "reliability": {
-            "type": "Property",
-            "value": 0.7
-         },
-         "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-         }
-      },
-      "totalSpotNumber": {
-         "type": "Property",
-         "value": 100
-      },
-      "location": {
-         "type": "GeoProperty",
-         "value": {
-            "type": "Point",
-            "coordinates": [
-               -8.6,
-               41.3
-            ]
-         }
-      },
-      "@context": [
-         "http://example.org/ngsi-ld/latest/parking.jsonld",
-         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-      ]
-   }
-]
-

C.5.16 Temporal Scope Queries

-

C.5.16.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the speed of all the Entities of type “Vehicle” that have been within the Scope /Madrid/Centro between the 1 st of August 2018 at noon and the 1 st of August 2018 at 01 PM. Note that the value of the Scope has to match for the given timeframe, which means it is possible that it has been set before, e.g. on 1 st of August 2018 at 11 AM.

-
-
-

C.5.16.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ=“/Madrid/Centro”

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.16.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-

Vehicle B9211 has already been within the Scope /Madrid/Centrobefore the beginning of the request interval, whereas Vehicle A8311 only entered the Scope within the request interval. Thus in the latter case only Property values are included that have been observed after the Scope has become valid.

-

C.6 Date Representation

-

In NGSI-LD, a TemporalProperty is represented only by its value, i.e. no sub-Properties of TemporalProperty nor sub-Relationships of TemporalProperty can be conveyed. In more formal language, a TemporalProperty does not allow reification. The term TemporalProperty has been reserved for non-reified structural timestamps (observedAt, createdAt, modifiedAt, deletedAt), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as timeproperty in Temporal Queries as mandated by clause 4.11.

-

The following examples show how time values (Date, Time, or DateTime) can be represented in NGSI-LD as reified Properties. For a reified Property whose value is assigned the JSON type Date, DateTime or Time, one mechanism is to use the Property’s valueType to hold the datatype (“Date”, “Datetime” or “Time”), as shown below:

-

Alternatively the data can be a structured to use the JSON-LD @value syntax structure, as shown below:

-

A third alternative to achieve the same result would be to use JSON-LD “type coercion”. With type coercion, values with a special data type are defined with @type in the @context. This enforces the correct type for any occurrence. Such an @context fragment is shown below:

-

The above does not work, when using the @context to perform compaction, in the normalized and compact representation of NGSI-LD, due to reification of the Property, because in this case testedAt is a complex JSON object, which cannot be compacted to a DateTime type as the @context specifies. Thus, the full URI http://example.org/test/testedAt is kept, instead of the short name testedAt. In summary, user @contexts used for the normalized and compact NGSI-LD representation cannot use the JSON-LD type coercion feature.

-

However, in the simplified (keyValue) representation case, such an @context with the specification of testedAt could be used, as there is no reification.

-

As a side note, when using the above @value + @type approach, since type is mapped to @type in the NGSI-LD core @context, JSON-LD compaction will result in the following compacted value, instead of the one shown above, because @type is compacted to type:

-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "scope": {
-     "type": "Property",
-      "values": [
-        [
-          "/Madrid/Centro",
-          "2018-08-01T11:00:00Z"
-        ]
-     ]
-       },  
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          30,
-          "2018-08-01T12:03:00Z"
-        ],
-        [
-          60,
-          "2018-08-01T12:05:00Z"
-        ],
-        [
-          50,
-          "2018-08-01T12:07:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  },
-  {
-    "id": "urn:ngsi-ld:Vehicle:A8311",
-    "type": "Vehicle",
-    "scope": {
-     "type": "Property",
-      "values": [
-        [
-          [
-             "/Madrid/Centro",
-             "/Company123/UnitA"
-          ],
-          "2018-08-01T12:10:00Z"
-        ]
-     ]
-       },  
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          40,
-          "2018-08-01T12:12:00Z"
-        ],
-        [
-          60,
-          "2018-08-01T12:14:00Z"
-        ],
-        [
-          50,
-          "2018-08-01T12:16:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-{
-  "id": "urn:ngsi-ld:Vehicle:B9211",
-  "type": "Vehicle",
-  "testedAt": {
-    "type": "Property",
-    "value":"2018-12-04T12:00:00Z"
-    "valueType": "DateTime"
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:Vehicle:B9211",
-  "type": "Vehicle",
-  "testedAt": {
-    "type": "Property",
-    "value": {
-      "@type": "DateTime",
-      "@value": "2018-12-04T12:00:00Z"
-    }
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-"testedAt": {
-  "@type": "https://uri.etsi.org/ngsi-ld/DateTime",
-  "@id": "http://example.org/test/testedAt"
-}
-"value": {
-  "type": "DateTime",
-  "@value": "2018-12-04T12:00:00Z"
-}
-

C.7 @context utilization clarifications

-

When expanding or compacting JSON-LD terms, the JSON-LD @context to be used is always the one provided in the current API request. For the benefit of users and implementers the following examples illustrate this concept.

-

The scenario starts with the creation of an Entity using a JSON-LD @context as follows:

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/ld+json

-
-
-

Content-Length: 200

-
-

The content of the @context utilized for the referred Entity creation (at http://example.org/ngsi-ld/latest/parking.jsonld) is as follows:

-

At Entity creation time the implementation will perform the expansion of terms using the JSON-LD @context depicted above.

-

Now it is needed to retrieve our initial Entity. For retrieving such Entity, this time, a different JSON-LD @context is going to be utilized, as follows:

-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffStreetParking",
-  "name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "availableSpotNumber": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-     },
-  "totalSpotNumber": {
-    "type": "Property",
-    "value": 200
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-"OffStreetParking": "http://example.org/parking/OffStreetParking",
-"availableSpotNumber": "http://example.org/parking/availableSpotNumber",
-"totalSpotNumber": "http://example.org/parking/totalSpotNumber",
-"name": "http://example.org/parking/name"
-}
-{
-"OffP": "http://example.org/parking/OffStreetParking",
-"ava": "http://example.org/parking/availableSpotNumber",
-"total": "http://example.org/parking/totalSpotNumber"
-}
-

This new @context, even though it makes use of the same set of Fully Qualified Names, is defining new short strings as terms. The reasons for that could be multiple: to facilitate data consumption by clients, to save some bandwidth, to enable a more (or less) human-readable response payload body in a language different than English, etc.

-

In this particular case, the result of the Entity retrieval will be as depicted below. It can be observed that the terms defined by the JSON-LD @context provided at retrieval time are used to render the Entity content (compaction), and not the terms that were provided at creation time (which may be no longer known by the broker).

-

It is also interesting to note that the @context array of the response payload body contains, indeed, our header-supplied @context:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffP",
-  "name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "ava": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-  },
-  "total": {
-  "type": "Property",
-    "value": 200
-    },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-
-

Another interesting case to note is the one when an @context with no matching terms or no @context at all is supplied. See the following example:

-
-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1

-
-
-

Accept: application/ld+json

-
-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "http://example.org/parking/OffStreetParking",
-  "http://example.org/parking/name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "http://example.org/parking/availableSpotNumber": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-  },
-  "http://example.org/parking/totalSpotNumber": {
-    "type": "Property",
-    "value": 200
-  },
-  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-}
-

In this particular case it can be observed that the user names (Entity Type, Attributes) in the response payload body have not been compacted, and as a result the Fully Qualified Names are included. However, the core API terms have been compacted, as the Core @context is always considered to be implicitly present if not specified explicitly (and that is why it is included in the JSON-LD response, as mandated by the specification).

- -

The JSON-LD Specification [2] states clearly that only one HTTP Link header with the link relationship <http://www.w3.org/ns/json-ld#context> is required to appear. Such statement has implications in terms of providing the JSON-LD @context when using the NGSI-LD API. The main implication is that if the @context is a compound one, i.e. an @context which references multiple individual @context, served by resources behind different URIs, then a wrapper @context has to be created and hosted. The final aim is that only one @context is referenced from the JSON-LD Link header. This can be illustrated with an example:

-

Imagine that it is desired to create an Entity providing @context terms which are defined in two different JSON-LD @context resources:

-
- -
-

If a developer wants to reference these two @context resources from a Link header, a wrapper @context can be easily created as follows:

-
{
-   "@context": [
-       "http://example.org/vehicle/v1/vehicle-context.jsonld",
-       "https://schema.org",
-       "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-   ]
-}
-

As such wrapper @context needs to be referenced from a Link header by using a URI, then it will have to be hosted at some place on the Web. Usually, developers will host @context using popular and simple solutions such as GitHub or GitLab pages. As a result, developers will be able to use @context in queries or when using “application/json” as main content type managed by their applications.

-

It is a good practice to include the Core @context in the wrapper @context so it can be used, off-the-shelf, by external JSON-LD processing tools. However, it should be noted this is not necessary for NGSI-LD, as the Core @context is always implicitly included.

-

Then, using such wrapper @context, (in our example hosted at https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), the developer will be able to issue requests like:

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/json

-
-
-

Content-Length: 200

-
-
-

Link: <https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-    "id": "urn:ngsi-ld:Vehicle:V1",
-    "type": "Vehicle",
-    "builtYear": {
-    "type": "Property",
-        "value": "2014"
-    },
-    "speed": {
-        "type": "Property",
-        "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-    }
-}
-
-

201 Created

-
-
-

Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1

-
-
-

Link: < https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld >; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1

-
-
-

Accept: application/ld+json

-
-
-

Link: <https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-

Observe that in this case the broker is responding with the same wrapper @context in the Link header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is “application/ld+json”). However, that could not be always the case, as there could be situations where the broker could need to provide a wrapper @context hosted by itself, for instance, when there are inline @context terms or when the Core @context has not been previously included by the wrapper @context (not recommended) provided within developer’s requests.

-

C.9 @context processing clarifications

-

JSON-LD Specification [2] says that “If a term is redefined within a context, all previous rules associated with the previous definition are removed”. In addition, it is stated that “Multiple contexts may be combined using an array, which is processed in order”.

-

In contrast to the JSON-LD Specification, the NGSI-LD specification states that the Core @context is protected and has to remain immutable. This essentially means that the Core @context has final precedence and, therefore, is always to be processed as the last one in the @context array. For clarity, data providers should place the Core @context in the final position. From the point of view of Data providers, care has to be taken so that there are no unexpected or undesired term expansions. See the following example:

-

The problem of the example above is that the term ”location” is defined in both the Core @context and the schema.org user @context and the Core @context takes precedence for the expansion. In these situations, if one wanted to refer to the schema.org “location”, the solution is to prefix the conflicting terms, so that there cannot be any clashing. Therefore, if the intent is to refer to <https://schema.org/location> throughout, the example above can be modified as shown below:

-

Note that the Core @context should be placed in the last position of the @context array. NGSI-LD implementations are required to render content following this approach, which has been undertaken in order to maximize compatibility with JSON-LD processing tools. This example works because the “schema:” prefix has already been defined by the schema.org @context.

-

C.10 ValueType datatype utilization clarifications

-

Using JSON-LD [2] syntax, typed values can be expressed using the JSON-LD @type keyword when defining a term, where @type value holds a URI which indicates the value’s datatype. However, it can be desirable for a Context Broker to be able to hold simpler untyped values within a Property’s value attribute and separately use a Property’s valueType to hold the value’s datatype. This format can be used to accommodate multiple acceptable datatype formats for the data to be held within a single Property and still hold sufficient meta data to be able to distinguish between them.

-

For example, consider an ontology for an Entity of type “Place” which has an address Property, where the address Property can either be an unstructured address in the form of a “String”or a structured “PostalAddress” JSON Object with street, city and country attributes - the following JSON-LD schema can be defined:

-

Example JSON-LD schema

-

Then the following two Entities of type “Place”can be created using the address.valueType Property to distinguish between the two formats:

-
{
-    "id": "urn:ngsi-ld:Vehicle:V1",
-    "type": "Vehicle",
-    "builtYear": {
-    "type": "Property",
-        "value": "2014"
-    },
-    "speed": {
-        "type": "Property",
-        "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-    },
-    "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld"
-}
-{
-    "id": "urn:ngsi-ld:Building:B1",
-    "type": "Building",
-    "name": {
-    "type": "Property",
-        "value": "Empire State"
-    },
-    "location": {
-        "type": "Property",
-        "value": "20 West 34th Street, New York City, NY 10001"
-    },
-    "@context": [
-        "https://schema.org/version/latest/schemaorg-current-https.jsonld",
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Building:B1",
-    "type": "Building",
-    "name": {
-        "type": "Property",
-        "value": "Empire State"
-    },
-    "schema:location": {
-        "type": "Property",
-        "value": "20 West 34th Street, New York City, NY 10001"
-    },
-    "@context": [
-        "https://schema.org/version/latest/schemaorg-current-https.jsonld",
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "example": "http://example.org/",
-    "xsd": "http://www.w3.org/2001/XMLSchema#",
-    "address": "example:address",
-    "city": "example:city",
-    "country": "example:country",
-    "street": "example:street",
-    "Place": "example:Place"
-    "PostalAddress": "example:PostalAddress",
-    "String": "xsd:String"
-}
-[
-    {
-        "id": "urn:ngsi-ld:Place:27182",
-        "type": "Place",
-        "address": {
-            "type": "Property",
-            "value": "Pariser Platz, Berlin, Germany",
-            "valueType": "String"
-        }
-    },
-    {
-        "id": "urn:ngsi-ld:Place:31415",
-        "type": "Place",
-        "address": {
-            "type": "Property",
-            "value": {
-                "street": "Straße des 17. Juni",
-                "city": "Berlin",
-                "country": "Germany"
-            },            "valueType": "PostalAddress"
-        }
-    }
-]
-

C.11 Entity with digital signature for a Property

-

As specified in [35], the atomic piece of information that creators can digitally sign in an NGSI-LD ecosystem is each single Attribute of an Entity. In the following example, an Entity of type “Store” with two Properties, “address” and “location” is presented. The “address” Property is digitally signed. The signature is created using one Ed25519 instantiation of the Edwards-Curve Digital Signature Algorithm (EdDSA).The used crypto suite is “eddsa-rdfc-2022”.

-
-
-

EXAMPLE:

-
-
-

Entity of type “Store” with two Properties. The “address” Property is digitally signed.

-
{
-"id": "urn:ngsi-ld:Store:002",
-"type": "Store",
-"address": {
-"type": "Property",
-"value": {
-"streetAddress": ["Tiger Street 4", "al"],
-"addressRegion": "Metropolis",
-"addressLocality": "Cat City",
-"postalCode": "42420"
-}
-"ngsildproof": {
-"type": "Property",
-"entityIdSealed": "urn:ngsi-ld:Store:002",
-"entityTypeSealed": "Store",
-"value": {
-"type": "DataIntegrityProof",
-"created": "2025-01-27T21:02:24Z",
-"verificationMethod":
-"https://example.edu/issuers/565049#z6MkwXG2WjeQnN....Hc6SaVWoT",
-"cryptosuite": "eddsa-rdfc-2022",
-"proofPurpose": "assertionMethod",
-"proofValue":
-"z3XrH3diVCqpVHXkE7WbnictqyQCkJBGTx....NRTzmuoWU1Y2FyqGfSV9eS"
-}
-}
-},
-"location": {
-"type": "GeoProperty",
-"value": {
-"type": "Point",
-"coordinates": [57.5522, -20.3484]
-}
-},
-"@context": "https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld"
-}
-
-
- - diff --git a/API-html/16-annex-d-informative-transformation-algorithms.html b/API-html/16-annex-d-informative-transformation-algorithms.html deleted file mode 100644 index 43828fbbe0b6e524cca0451bd7b0b1140f52a271..0000000000000000000000000000000000000000 --- a/API-html/16-annex-d-informative-transformation-algorithms.html +++ /dev/null @@ -1,1644 +0,0 @@ - - - - - - - -Annex D (informative): Transformation Algorithms - - - - - - - - -

Annex D (informative): Transformation Algorithms

-

D.1 Introduction

-

These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification [2]).

-

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

-

This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated @context) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model.

-
-
-

NOTE:

-
-
-

An early implementation of this algorithm can be found at [i.5].

-
-
-

Let:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

The algorithm should run as follows, provided all the preconditions defined above are satisfied:

-
-
    -
  1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> … <"AliasTn", Tn>.
    2. -
  2. Add to O two new members:
    3. -
-
-
-
    -
  1. <"id", I>.
    2. -
-
-
-
    -
  1. <"type", "AliasT"> or <"type", ["AliasT1", ...,"AliasTn"]> .”>.
    2. -
-
-
-
    -
  1. For each Property Psi (Pi, “AliasP”, Vi, Di) associated to N:
    2. -
-
-
-
    -
  1. Run Algorithm ALG1.1 taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. For each Relationship Rs (Ri, AliasRi, Robji) associated to N:
    2. -
-
-
-
    -
  1. Run Algorithm ALG1.2 taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. Return (O, C) and end of the algorithm.
    2. -
-
-

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

-

Let Ps be the Property that has to be transformed. It is defined by (P, “AliasP”, V, D), where P denotes a Property Type Id, “AliasP” is the Property name, V is the Property Value and D is the Property Value’s data type.

-

Ps might be associated to extra Properties or Relationships.

-

Let O be the output JSON-LD object and C the associated JSON-LD context:

-
-
    -
  1. Execute the following steps:
    2. -
-
-
-
    -
  1. If no member with “AliasP” is present in O, add a new member to O with key “AliasP” and value an object structure, let it be named Op as defined in the following. Otherwise, add all existing members with “AliasP” to a JSON-LD array and in addition put the object structure Op as defined in the following:
    2. -
-
-
- -
-
-
    -
  1. <"@type", D>.
    2. -
-
-
-
    -
  1. <"@value", V>.
    2. -
-
-
- -
-
-
    -
  1. <"value", V>.
    2. -
-
-
-
    -
  1. Add a new member to C as follows:
    2. -
-
-
- -
-
-
    -
  1. For each Property associated to Ps (Pss) recursively run the present algorithm (ALG1.1) taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. For each Relationship associated to Ps (Rss) run algorithm ALG1.2 taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. Return (O,C) and end of the algorithm.
    2. -
-
-

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

-

Let Rs be the Relationship that has to be transformed. It is defined by (R, “AliasR”, Robj), where R denotes a Relationship Type Id, “AliasR” is the Relationship’s name and Robj is the identifier of the target object of the Relationship.

-

Rs might be associated to extra Properties or Relationships.

-

Let O be the output JSON-LD object and C the current JSON-LD context:

-
-
    -
  1. Execute the following statements:
    2. -
-
-
-
    -
  1. If no member with “AliasR” is present in O, add a new member to O with key “AliasR” and value an object structure, let it be named Or, and defined as in the following. Otherwise, add all existing members with “AliasR” to a JSON-LD array and in addition put the object structure Or as defined in the following:
    2. -
-
-
- -
-
-
    -
  1. For each Property associated to Rs (Pss) run the algorithm ALG1.1 taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. For each Relationship associated to Rs (Rss) recursively run the present algorithm ALG1.2 taking the following inputs:
    2. -
-
-
- -
-
-
    -
  1. Return (O,C) and end of the algorithm.
    2. -
-
- - diff --git a/API-html/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html b/API-html/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html deleted file mode 100644 index c72b1d7b26a28e64c16a87a719311f2904156ccd..0000000000000000000000000000000000000000 --- a/API-html/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html +++ /dev/null @@ -1,1410 +0,0 @@ - - - - - - - -Annex E (informative): RDF-compatible specification of NGSI-LD meta-model - - - - - - - - -

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

-

The content of this annex is now in ETSI GS CIM 006 [i.8].

- - diff --git a/API-html/18-annex-f-informative-conventions-and-syntax-guidelines.html b/API-html/18-annex-f-informative-conventions-and-syntax-guidelines.html deleted file mode 100644 index 2af386df05eafc477389692f93fe5c6ffd5ce215..0000000000000000000000000000000000000000 --- a/API-html/18-annex-f-informative-conventions-and-syntax-guidelines.html +++ /dev/null @@ -1,1483 +0,0 @@ - - - - - - - -Annex F (informative): Conventions and syntax guidelines - - - - - - - - -

Annex F (informative): Conventions and syntax guidelines

-

When new terms are defined, they are marked in bold, and terms are capitalized thereafter.

-
-
-

EXAMPLE 1:

-
-
-

NGSI-LD Linked Entity , Linked Entity .

-
-
-

API Parameter names are always in lowercase.

-
-
-

EXAMPLE 2:

-
-
-

options .

-
-
-

Entity Types are defined using lowercase but with a starting capital letter.

-
-
-

EXAMPLE 3:

-
-
-

Vehicle, Building, ParkingSpace.

-
-
-

JSON-LD nodes and terms are always defined using camel case notation starting with lower case.

-
-
-

EXAMPLE 4:

-
-
-

createdAt , value , unitCode .

-
-
-

When referring to special terms, data types or words defined previously in the present document or by other referenced specifications, italics format is used.

-
-
-

EXAMPLE 5:

-
-
-

ListRelationship, GeoProperty, Geometry, Second, Number .

-
-
-

When referring to literal strings double quotes are used.

-
-
-

EXAMPLE 6:

-
-
-

“application/json” , “Subscription” .

-
-
-

When referring to the JSON-LD Context the mnemonic text string @context is used as a placeholder.

-

All the dates and times are given in UTC format.

-
-
-

EXAMPLE 7:

-
-
-

2018-02-09T11:00:00Z .

-
-
-

The measurement units used in the API are those defined by the International System of Units.

-
-
-

EXAMPLE 8:

-
-
-

The distance in geo-queries is provided in meters.

-
-
-

When defining application-specific elements or API extensions the same conventions and syntax guidelines should be followed.

- - diff --git a/API-html/19-annex-g-informative-localization-and-internationalization-support.html b/API-html/19-annex-g-informative-localization-and-internationalization-support.html deleted file mode 100644 index 5a288b1a166026fda942ccb06ca7dd7c744bb53c..0000000000000000000000000000000000000000 --- a/API-html/19-annex-g-informative-localization-and-internationalization-support.html +++ /dev/null @@ -1,1603 +0,0 @@ - - - - - - - -Annex G (informative): Localization and Internationalization Support - - - - - - - - -

Annex G (informative): Localization and Internationalization Support

-

G.0 Foreword

-

These algorithms described below are informative, but NGSI-LD implementations should aim at either implementing them as they are described here or providing equivalent @context elements for their payloads to provide interoperability with their internationalized context entities.

-

G.1 Introduction

-

G.1.0 Foreword

-

Since Internationalization is not core to context information management, any direct support within NGSI-LD systems is limited. Annex G proposes a series of best practices for maintaining, querying and displaying interoperable internationalized data.

-

The content of the @context utilized for the referred Entities within these examples uses pre-existing URNs used for internationalization and is as follows:

-

G.1.1 Associating an Entity with a Natural Language

-

Where a context Entity is associated with a single natural language, include a well-defined Property indicating the natural language of the content. For example an Event taking place in French may be defined as follows:

-

G.1.2 Associating a Property with a Natural Language

-

Where a Property of a context entity can be associated to one more natural language, include additional metadata as a sub-Property of that Property. For example, a Hotel with booking forms available in English, French and German may be defined as follows:

-

G.1.3 Associating as equivalent entity

-

Where equivalent context entities in multiple natural languages exist, they may be associated with each other through the use of a one-to-many relationship, where each relationship holds an additional sub-Property indicating the natural language of the equivalent entities.

-

For example, three Events (such as a walking tour which is available in English, French and German) may be associated to each other as follows:

-
{
-"inLanguage": "http://schema.org/inLanguage",
-"sameAs": "http://schema.org/sameAs"
-}
-{
-    "type": "Event",
-    "id": "urn:ngsi-ld:Event:bonjourLeMonde",
-    "name": {
-        "type": "Property",
-        "value": "Bonjour le Monde" 
-    },
-    "description": {
-         "type": "Property",
-         "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple" 
-    },
-    "inLanguage": {
-        "type": "Property",
-        "value": "fr"   
-    }
-}
-{
-    "type": "Hotel,
-    "id": "urn:ngsi-ld:Hotel:XXXXX",
-    "name": {
-        "type": "Property",
-        "value": "Grand Hotel" 
-    },
-    "bookingUrl": {
-        "type": "Property",
-        "value": [
-            "http://example.com/booking-in-french/", 
-            "http://example.com/booking-in-english/", 
-            "http://example.com/booking-in-german/"
-        ],
-        "inLanguage": { 
-            "type": "Property", 
-            "value": ["fr", "en", "de" ]
-        }
-    }
-}
-{
-    "type": "Event",
-    "id": "urn:ngsi-ld:Event:bonjourLeMonde",
-    "name": {
-        "type": "Property",
-        "value": "Bonjour le Monde" 
-    },
-    "sameAs": [
-        {
-            "type": "Relationship",
-            "datasetId" : "urn:ngsi-ld:Relationship:1",
-            "object": "urn:ngsi-ld:Event:helloWorld",
-            "inLanguage": {
-                    "type": "Property",
-                    "value": "en"   
-            }
-        },
-        {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Event:halloWelt",
-            "inLanguage": {
-                    "type": "Property",
-                    "value": "de"   
-            }
-        }
-    ]
- }
-

G.2 Natural Language Collation Support

-

G.2.0 Foreword

-

All strings within an NGSI-LD system are defined and sorted as a sequence of Unicode characters. As such there is no simple collation mechanism to query entities ignoring case, diacritic marks or matching diphthong single letters such as the German “ö” to also match with “oe”.

-

Many databases support a degree of natural language support, in general collation support will always depend upon the underlying database and as such will vary from implementation to implementation. This therefore and cannot be standardized and exposed as part of the context information management API. Furthermore, collation is slow and processor intensive, and for massive systems is better achieved using a separate index.

-

For systems that require it, this clause proposes a mechanism as an extension to a NGSI-LD Context Broker which can be modified and used to offer collation support to the natural language attributes found within context entities where necessary through creating, querying and maintaining an additional property of a property for collated attributes.

-

G.2.1 Maintain collations as metadata

-
- -
-
-

str.normalize(“NFD”).replace(/[\u0300-\u036f]/g, ““).toLower()

-
-

Other substitutions could be made where local spelling rules vary (for example different for German ö = oe).

-

G.2.2 Route language sensitive queries via a proxy

-

Create a simple forwarding proxy around the NGSI-LD system. For any urls with a q param (and a collate flag) run a clean-up of the q param and amend the query string:

-

The following request on the proxy:

-
-

GET /ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name

-
-

is altered on the fly and is sent to the NGSI-LD system as shown:

-
-

GET /ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22

-
-

Once again, the substitutions to make to the query string will depend on the rules of the natural language to be supported.

-

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

-

G.3.0 Foreword

-

Context data entities are designed to be interoperable and therefore all dates are held as UTC dates, all currency amounts are held as JSON numbers (with the unitCode property-of-a-property available to hold the currency), etc. Localization should not occur within the context data entities themselves. Offering fully localized responses is not a concern of the NGSI-LD API.

-

If localization support is necessary, a simple proxying a conversion mechanism could be used to amend the context data received from the NGSI-LD system before being passed to a third party system for display.

-

G.3.1 Localizing Dates

-

For example, if a system needs to display DateTime data in Islamic Date format

-

The following request on the proxy:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified

-
-

is forwarded unaltered and is sent to the NGSI-LD system as shown:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified

-
-

The response from the NGSI-LD system is always in UTC format:

-

And the proxy can be used to update this to the desired format:

-

Using an internationalization script such as the following:

-
    {"date": "2020-09-28T17:13:39+02:00"}
-    {"date": "11 Safar, 1442 1:13:39PM"}
-new Intl.DateTimeFormat("en-u-ca-islamic", {day: 'numeric', month:
-'long',weekday: 'long',year : 'numeric'}).format(date);
-

It should be noted that post-localization, the transformed date is no longer valid NGSI-LD.

- - diff --git a/API-html/2-foreword.html b/API-html/2-foreword.html deleted file mode 100644 index 2858c63f9199b9923e50f9fe3a0b075d78389ae9..0000000000000000000000000000000000000000 --- a/API-html/2-foreword.html +++ /dev/null @@ -1,1410 +0,0 @@ - - - - - - - -Foreword - - - - - - - - -

Foreword

-

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

- - diff --git a/API-html/20-annex-h-informative-suggested-actuation-workflows.html b/API-html/20-annex-h-informative-suggested-actuation-workflows.html deleted file mode 100644 index 0bc9af41f489647e484b6358c7022daf284928c1..0000000000000000000000000000000000000000 --- a/API-html/20-annex-h-informative-suggested-actuation-workflows.html +++ /dev/null @@ -1,1781 +0,0 @@ - - - - - - - -Annex H (informative): Suggested actuation workflows - - - - - - - - -

Annex H (informative): Suggested actuation workflows

-

H.1 Actuators and feedback to the consumer

-

Actuators are things that can change their state (light on/off) or execute actions (move forward, detect face, etc.).

-

There is currently no explicitly and precisely specified support for actuation in the NGSI-LD API. Thus, this clause describes some conventions that represent a proposed best-practice about how NGSI-LD API and data models can be used for the interaction between applications and actuators represented by NGSI-LD Entities.

-

The conventions and approach described in this clause are not powerful enough to implement complex actuation jobs that depend on each other and, for instance, make actuation decisions conditional on the outcome of other actuations, unless that behaviour is implemented in a custom way within the application logic. The concept of a more evolved service execution logic, being a first-class citizen of the NGSI-LD API and able to offer more structured building blocks for actuation, is outside the scope of this annex.

-

An NGSI-LD system that comprises an actuator and supports actuation workflows is represented as one or more NGSI-LD Entities, plus a Context Broker, a Context Source or a Context Producer, and a Context Consumer, which collaborate.

-

The interaction between actuator and Context Consumer needs to be bidirectional. Thus, actuators are triggered by the reception of actuation-specific commands (e.g. “set the on state of the lamp to false”, to turn the light off) that are encoded as NGSI-LD data, following a suggested data model. They respond with feedback, similarly encoded as NGSI-LD data.

-

Command feedbacks may serve to control the maximum operations rate a controlling application needs to achieve, and different levels of feedback can be requested, by associating a specific Quality of Service value to the command:

-
- -
-

H.2 Architecture for actuation

-

In this architecture, the application acts as Context Consumer, and the terms are used interchangeably.

-

Commands are sent to the Context Broker by the Context Consumer, using the standard NGSI-LD API and a suggested convention for representing them. In turn, feedback about command execution is received by the Context Consumer, both as continuous status updates and/or a final command result.

-

More specifically, the component that handles direct communication with the actuator is the Context Source or the Context Producer: it uses an actuator-specific protocol to control the actuator and get responses and updates from it, i.e. from the real system. Such Context Source/Consumer or Context Producer/Storage acting as a proxy or intermediary to the actuator is referred to, in the following, as Context Adapter.

-

Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD command requests from the NGSI-LD Context Broker and send back command status and result to it, as well as using an actuator-specific protocol to communicate with the actuator.

-

The NGSI-LD Context Broker is responsible for handling direct communication with the Context Consumer.

-

Thus, to support actuation, there is a need to specify:

-
- -
-
-

-
-
-

Figure H.2-1: Architecture for actuation

-
-

H.3 Structure of Commands and additional Properties

-

H.3.0 Introduction

-

The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing the actuator’s status, a set of additional, dedicated NGSI-LD Properties associated with:

-
- -
-

The structure of the commands needs to be specified, but not the internal format of their payloads. By using commands with a custom payload, one can support all kinds of operations, for example:

-
- -
-

The data model for command requests, status and responses has to include metadata such as the QoS of the command, its identifier, and the custom payload itself.

-

Both the requests/responses and the list of commands the NGSI-LD system is able to support can be represented with additional NGSI-LD Properties, as follows.

-

H.3.1 Property for listing available commands

-

The additional Property dedicated to the list of available commands is as follows:

-
"commands": {
-  "type": "Property",
-  "value": ["`<cmd_name1>`","`<cmd_name2>`", …, "`<cmd_nameN>`"]
-}
-

It is a Property whose value is an array of Strings, each string representing the unique name of a supported command.

-

H.3.2 Properties for command endpoints

-

For each available command, a set of three endpoints is to be additionally created within the NGSI-LD system, by means of three dedicated Properties per command. The first endpoint will manage that command’s requests, the second endpoint will manage its status, and the third endpoint will manage command’s results.

-

This convention dictates that:

-
- -
-

Each endpoint can receive multiple requests or responses, and it supports queueing of messages. For example, the command moveToLocation may receive a sequence of requests that are to be stored in an array and orderly processed depending on the arrival timestamps. A number of respective responses may be produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD Property, exploits the multi-Attribute feature (see clause 4.5.5), as follows:

-

Command Request endpoint

-

Command Status endpoint

-

Command Result endpoint

-
"`<cmd_name>`": {
-  "datasetId": a URI uniquely identifying the specific command request
-               (optional, if the use case does not need command queueing),
-  "type":      "Property",
-  "qos":       an Integer, representing the desired QoS (optional, default=0),
-  "value":     custom parameters of the command (mandatory)
-}
-"`<cmd_name>`-STATUS": {
-  "datasetId": a URI uniquely identifying the specific status feedback message
-               (optional, if the use case does not need queueing them),
-  "type":      "Property",
-  "value":     custom status of the command (mandatory)
-}
-"`<cmd_name>`-RESULT": {
-  "datasetId": a URI uniquely identifying the specific result feedback message
-               (optional, if the use case does not need queueing them),
-  "type":      "Property",
-  "value":     custom result of the command (mandatory)
-}
-

Usually, the Context Adapter (or the actuator behind it), upon receiving a command request with a specific datasetId, will then generate status and result with the same datasetId, so that, when the status/result is received by the application, it can link it back to the corresponding command that is generating the received feedback. The value of the request, status and result is generic, and it is up to the specific application to define useful values. As an example, the PackML language for the control of packaging machines defines a set of possible values for statuses during an actuation workflow.

-
-
-

EXAMPLE 1:

-
-
-

An example follows, where the NGSI-LD system represents a simple actuator. The example shows the NGSI-LD Entity representing a light that can change colour by manipulation of its brightness, hue and saturation values; further, it is possible to turn the lamp on and off. Apart from the id and the type , the actuator entity has a set of regular properties that represent the current status of the lamp. In the example these are colorRGB and is-on . Then it has the conventional Property named commands , signalling that it supports four commands: “turn-on” , “set-saturation” , “set-brightness” , “set-hue” . Further, it has four (times three) additional properties serving the purpose of command endpoints.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  REGULAR PROPERTIES
-  "colorRGB": {"type": "Property", "value": "0xABABAB"},
-  "is-on": {"type": "Property", "value": true},
-  AVAILABLE COMMANDS
-  "commands": {
-    "type": "Property",
-    "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"]
-  }
-  COMMAND ENDPOINTS
-  "turn-on": {"type": "Property", "value": `<custom request>`}
-  "turn-on-STATUS": {"type": "Property", "value": `<custom status>`}
-  "turn-on-RESULT": {"type": "Property", "value": `<custom response>`}
-  "set-hue": ...
-  "set-hue-STATUS": ...
-  "set-hue-RESULT": ...
-  …
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

The following example shows an NGSI-LD Entity Fragment that can be used as a command request to request that the lamp be turned off.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  "turn-on": { 
-    "type": "Property",
-    "qos": {
-      "type": "Property",
-      "value": 1
-    },
-    "value": false
-  }
-}
-
-
-
-
-

EXAMPLE 3:

-
-
-

In the following example, the value of the command request is a more complex JSON Object, to show that complex actions can be conveyed by just one request. Further, the request has an identifier that makes it possible to enqueue it, together with other request that may arrive to the same command endpoint within a timespan.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  "set-hue": { 
-    "type": "Property",
-    "qos": {
-      "type": "Property",
-      "value": 1
-    },
-    "datasetId": "myapp:mycommand:1342",
-    "value": {"red": "1 seconds", "green": "2 seconds"}
-  }
-}
-
-
-

In summary, the suggested convention prescribes a commands property that contains a list of commands supported by the actuator. For each of these commands, the convention requires a command endpoint consisting of three properties, the name of the command, e.g. “turn-on”, the status property, which is the name of the command with ”-STATUS” as suffix, and the result, which is the name of the command with “-RESULT” as suffix. Nevertheless, it is noted that such suffixes are just a convention to distinguish the endpoints. So far, two practical implementations exist, see clauses H.5 and H.6, that adopt the general scheme of this convention, with minor deviations. In fact, this convention is derived as a generalization that leverages the full potential of NGSI-LD sub-Attributes and multi-Attributes.

-

H.4 Communication model

-

H.4.1 Possible communication models

-

This convention can be leveraged by two different communication models:

-
- -
-

H.4.2 Subscription/notification model

-

For the interaction to work, the Context Adapter, acting as a proxy to the actuator, subscribes to all command properties; in example 1 of clause H.3.2, these are “set-brightness”, “set-saturation”, “set-hue” and “turn-on”. When the application, acting as the actuation client, updates the value of a command property, the Context Adapter will receive the notification with the new value. This will be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol. The application in turn can subscribe to the command status and the result. The Context Adapter updates the status of the actuation during the execution of the command, which is primarily relevant in the case of longer-lasting actuations, and finally updates the result once the actuation has been completed. If the application has subscribed to the status and result, it will receive the corresponding notifications. Independent of the command-related properties, the status of the actuator, held within its regular properties, will be updated.

-

The detailed workflow is depicted in Figure H.4.2‑1, and can be interpreted as follows:

-
-
    -
  1. Application updates turn-on command Property with “value”: true
    2. -
  2. Context Adapter gets notification of the new value true
    3. -
  3. Context Adapter updates turn-on-STATUS command Property with “value”: “PENDING”
    4. -
  4. Application gets notification of the new value “PENDING”
    5. -
  5. Context Adapter updates is-on regular Property with “value”: true
    6. -
  6. Application gets notification with value: true
    7. -
  7. Context Adapter updates turn-on-RESULT command Property with “value”: “OK”
    8. -
  8. Application gets notification with of the new value “OK”
    9. -
-
-
-

-
-
-

Figure H.4.2-1: Steps of the actuation workflow using subscription/notification

-
-

H.4.3 Forwarding model

-

The forwarding model uses registrations and forwarding of requests. Actuation of commands is provisioned via registration(s) to the NGSI-LD Registry done by the Context Adapter that states “I am responsible for command property <X>”. When the Application changes the value of a command property, first the NGSI-LD Context Broker asks to the NGSI-LD Registry whether the property is delegated to some other component. The NGSI-LD Registry knows that property <X> of the Entity is delegated to the Context Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the other communication model, the request will then be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol.

-

In this model, the NGSI-LD Entity is distributed over two different components, because some of its properties live in the Context Brokers and other properties live in the Context Adapter, as indicated in Figure H.4.3‑1 with a dotted rectangle.

-

The rest of the workflow, i.e. delivery of status and result messages to the application, is done similarly to the subscription/notification model. The detailed workflow is depicted in Figure H.4.3‑1, and can be interpreted as follows:

-
-
    -
  1. Application updates turn-on command Property with “value”: true
    2. -
-
-
-

2a) Context Broker ask Registry where to forward the request

-
-
-

2b) Context Broker forwards request to Context Adapter

-
-
-
    -
  1. Context Adapter updates turn-on-STATUS command Property with “value”: “PENDING”
    2. -
-
-
-
    -
  1. Application gets notification of the new value “PENDING”
    2. -
-
-
-
    -
  1. Context Adapter updates is-on regular Property with “value”: true
    2. -
-
-
-
    -
  1. Application gets notification with value: true
    2. -
-
-
-
    -
  1. Context Adapter updates turn-on-RESULT command Property with “value”: “OK”
    2. -
-
-
-
    -
  1. Application gets notification with of the new value “OK”
    2. -
-
-
-

-
-
-

Figure H.4.3-1: Steps of the actuation workflow using forwarding

-
-

H.5 Implementation of the subscription-based actuation workflow

-

The Fed4IoT project (<https://fed4iot.org>) leverages the NGSI-LD architecture and the subscription/notification workflow for actuation, in order to implement the concept of a Cloud of Things. It enables virtualization of existing IoT sensors/actuators through Virtual Things and IoT Brokers. IoT application developers can simply rent the Virtual Things and the Brokers their applications need.

-

The Fed4IoT’s Cloud of Things is named VirIoT (<https://github.com/fed4iot/VirIoT>), and it is based on the concept of Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, NGSI-LD, etc.).

-

In Figure H.5‑1 a diagram shows how VirIoT implements the concept of a large-scale and distribute NGSI-LD system that leverages the architecture and the workflow convention described in clause H.4.2.

-
-

-
-
-

Figure H.5-1: VirIoT implementation of the NGSI-LD system and actuation workflow

-
-

All components encapsulate requests in a neutral-format message that leverages NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data distribution system, all information and actuation commands are encoded as NGSI-LD entities, plus an additional “meta header” that is used by the MQTT to publish and subscribe in a broadcast fashion to multiple vThings, because the same virtual sensor can be used by multiple applications at the same time.

-

For the actuation workflow, the “data” part of this message contains the command request, as specified in clause H.3, but with an additional value key that is the “command notification uri” (cmd-nuri), representing a location where feedback (status, result) should be sent by the ThingVisor. For example, the cmd-nuri contains the “data_in” MQTT topic of the issuing vSilo, so that command feedbacks (status and results) are sent to it, only, instead of being broadcasted to all subscribing applications.

-

VirIoT is agnostic to access control issues to a virtual actuator, since the relevant policies are implemented in the specific ThingVisor, which can grant tokens to execute actuation-commands to a subset of vSilos only, through preliminary exchange of specific actuation-commands (a kind of log-in).

-

Fed4IoT has developed several different ThingVisors (Context Adapters for different sensors and hardware): for example, lamp systems and robot devices are virtualized through specific ThingVisors, and applications can control the lighting system of a rented conference room or control camera and position of a bot by adding related virtual actuators to their vSilo.

-

H.6 Implementation of the registration-based actuation workflow

-

The IoT Agent node library [i.22] introduces the concept of an IoT Agent, which is a component that lets a group of devices send their data to and be managed from a Context Broker using their own native protocols. Thus, it corresponds to the Context Adapter, and wires up the IoT devices so that measurements can be read and commands can be sent using NGSI-LD requests sent to an NGSI-LD compliant context Context Broker.

-

IoT Agents already exist or are in development for many IoT communication protocols and data models. Examples include the following:

-
- -
-

This implementation follows the communication model described in clause H.4.3, as explained in Figure H.6‑1. In this workflow:

-
- -
-
-

-
-
-

Figure H.6-1: IoT Agent node library implementation of the NGSI-LD system and actuation workflow

-
-

Provisioning of the devices will be carried out (via REST API) through IoT Agents, as well. This provisioning implies that, on the one hand, the corresponding entities (with their commands), that represent the devices, are generated in the Context Broker and, on the other hand, that the corresponding IoT Agent is configured for communication with the corresponding device, all in one provisioning step. Below, an example how to provision a device which supports start and stop commands is presented.

-
{
-    "devices": [
-        {
-            "device_id":   "device001",
-            "entity_name": "urn:ngsi-ld:Device:001",
-            "entity_type": "Device",
-            "attributes": [
-                { "object_id": "s", "name": "isOpen", "type": "boolean" }
-            ],
-            "commands": [
-                { "name": "start", "type": "command" },
-                { "name": "stop", "type": "command" }
-            ],
-            "static_attributes": [
-                { "name":
-                    { "type": "Text", "value": "Device:001 provision" }
-                }
-            ]
-        }
-    ]
-}
- - diff --git a/API-html/21-annex-i-informative-change-history.html b/API-html/21-annex-i-informative-change-history.html deleted file mode 100644 index 97b0ead2caa92f920e5828723cdbf9987fe6ed80..0000000000000000000000000000000000000000 --- a/API-html/21-annex-i-informative-change-history.html +++ /dev/null @@ -1,2599 +0,0 @@ - - - - - - - -Annex I (informative): Change history - - - - - - - - -

Annex I (informative): Change history

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Date -
-Version -
-Information about changes -
-February 2020 -
-

1.2.10

-
-Early draft copied from API version 1.2.1 -
-February 2020 -
-

1.2.11

-
-

Unicode characters. Query Language syntax changes to Attribute path, and extension to accept specifying just Query or Geoquery when Querying Entities

-

Acknowledgements to EU projects. Lightweight Figures

-
-March 2020 -
-

1.2.12

-
-

Extending to other interactions the above changes to query entities interaction

-

Changes to ABNF Query Language syntax to access complex objects value of properties more easily

-

Generalized Notification Headers, in order to carry authentication etc., info

-

Novel &option=count and associated Header to indicate number of Entities in response to a query

-

Novel/entityOperations/query and/temporal/entityOperations/query endpoints to perform query via POST

-

Clarified attrs URL parameter behaviour

-

Support for Multiple Attributes

-

Support for Multiple Tenants

-
-May 2020 -
-

Candidate 1.2.13

-
-

from 101r1: Multi-Attribute-Support-fix-in-4.5.5

-

from 102r1: Batch_Operation_Error_Codes

-

from 110r1: JSON-LD Validation clause

-

from 112r1: IRI Support for International Characters

-

from 115r2: More Core Context Changes

-

from 130: Entity Types

-

MQTT Notifications

-

GeoJSON Representation

-
-9 July 2020 -
-

1.3.1

-
-Technical Officer verifications for submission to editHelp! publication pre-processing -
-August 2020 -
-

1.3.2

-
-New baseline towards v1.4.1 -
-November 2020 -
-

1.3.3

-
-From 272r1: Support for natural languages via LanguageProperty; annex G -
-December 2020 -
-

1.3.4

-
-From 319: Align Table 6.8.3.2‑1 with clause 5.10.2 for query via attrs -
-December 2020 -
-

1.3.4

-
-From 310r2: Dot vs. comma in DateTime -
-December 2020 -
-

1.3.4

-
-From 309r1: Remove sentences referring to old multi attributes representation -
-December 2020 -
-

1.3.4

-
-From 308r: id and type for JSON-LD compliance -
-December 2020 -
-

1.3.4

-
-

From 313r1: FIXES to Cross domain data model for LanguageProperties

-

Bug fixes and errata

-
-December 2020 -
-

1.3.5

-
-From 275r3: Temporal Aggregation Functions -
-December 2020 -
-

1.4.0

-
-1.3.5 with small typos corrected, approved as 1.4.0 -
-January 2021 -
-

1.4.1

-
-ETSI Technical Officer review for ETSI EditHelp publication pre-processing -
-March 2021 -
-

1.4.2

-
-Editorial Changes, clarifications added, better references, figures replacements and corrections, figures merged, typos, code indentation -
-April 2021 -
-

1.4.2

-
-Temporal Pagination -
-April 2021 -
-

1.4.2

-
-Clarified behaviour when multiple instances of the same Entity are in an input array -
-July 2021 -
-

1.4.3

-
-From 130r6: NGSI-LD Scope -
-July 2021 -
-

1.4.3

-
-From 143r6: Storing, managing and serving @contexts -
-July 2021 -
-

1.4.3

-
-From 120r4: API structuring -
-October 2021 -
-

1.4.4

-
-From 156: Remove static elements from temporal representations -
-October 2021 -
-

1.4.4

-
-From 155: Existence query -
-October 2021 -
-

1.4.4

-
-From 152: Remove null value deletion -
-October 2021 -
-

1.4.4

-
-From 151: attrs missing in core context -
-October 2021 -
-

1.5.1

-
-ETSI Technical Officer review for ETSI EditHelp publication pre-processing -
-November 2021 -
-

1.5.2

-
-First early draft after EditHelp publication of V1.5.1 to prepare next V1.6.1 publication -
-January 2022 -
-

1.5.3

-
-Concise representation -
-May 2022 -
-

1.5.4

-
-PUT/PATCH Entity -
-May 2022 -
-

1.5.4

-
-Distributed operations -
-July 2022 -
-

1.5.5

-
-From 99r6: Deletions and advanced notifications -
-July 2022 -
-

1.5.5

-
-From 106r1: Workflow for actuation -
-July 2022 -
-

1.5.5

-
-From 105r1: Context Source Info in Context Source Registration -
-July 2022 -
-

1.5.5

-
-From 93r1: default context clarification -
-July 2022 -
-

1.5.5

-
-From 91r1: CR_on_Scope_ABNF_format -
-Juy 2022 -
-

1.6.1

-
-Final Technical Official check for EditHelp publication -
-October 2022 -
-

1.6.2

-
-

New early draft:

-

corrected Annex C6 date representation

-

from 149r3: generalized description of @context in bullet lists

-

Fixed usage of NGSI-LD Null in Attributes’ definitions

-
-December 2022 -
-

1.6.4

-
-From 188r2_Registration_Clarifications -
-December 2022 -
-

1.6.4

-
-From 182r2_Add_NGSI-LD_Roles_for_Context_Registration -
-December 2022 -
-

1.6.4

-
-From 156r2 VocabProperty/URI type coercion -
-December 2022 -
-

1.6.4

-
-177r2 Clarify usage of Accept, Content-Type and Linked @context when forwarding to partial Context Brokers -
-December 2022 -
-

1.6.4

-
-178 Add Batch Query to Federation Ops -
-December 2022 -
-

1.6.4

-
-183r1 Clarify Temporal query behaviour -
-December 2022 -
-

1.6.4

-
-149r4 Forbid scoped and nested @contexts -
-December 2022 -
-

1.6.4

-
-023006 Fixing CSource registration example in C.3 -
-December 2022 -
-

1.6.4

-
-Fix: Tenants URI becomes String -
-December 2022 -
-

1.6.4

-
-Fix: POST-QUERY-COUNT-PAGINATION -
-December 2022 -
-

1.6.4

-
-Fix: CHECK-URI-PARAM -
-December 2022 -
-

1.6.4

-
-Updated examples and text to context v1.7.jsonld -
-March 2023 -
-

1.6.6

-
-CIM(23)000006_Adding_previousValue_to_GeoProperty_type_definition -
-March 2023 -
-

1.6.6

-
-cSource -> CSource; “implementations shall do the following” -
-March 2023 -
-

1.6.7

-
-000013r4_Updated_Distributed_Execution_Behaviour -
-March 2023 -
-

1.6.8

-
-CIM(22)000195r3_type_passing_for_M2M_callReviewed -
-April 2023 -
-

1.6.9

-
-Fixing URI🡪String datatypes -
-June 2023 -
-

1.7.2

-
-CIM(23)000053r1_Entity_Graph_Retrieval (for FIWARE SUMMIT) -
-June 2023 -
-

1.7.3

-
-000056r2_APIv172_towards_v18.docx (for FIWARE SUMMIT) -
-October 2023 -
-

1.7.4

-
-From 25023r2: Use Temporal Evolution instead of Temporal Representation + Updated figures in clause 5 and 6 -
-November 2023 -
-

1.7.5

-
-

From 68r5: Additional id only format and attribute projection via pick and omit

-

From 121r1: Relationship as Array

-

From 123r1: URN Namespace Definitions

-

From 149r3: Allow Broader Local Requests

-

From 153r1: JsonProperty

-

From 159: Bug fixed in CIM 009: GeoJSON responses in figures

-

From 160: Replace Attribute fix

-
-December 2023 -
-

1.7.6

-
-

From 164: Host alias /info Endpoint

-

From 154r2: EntityMap

-

Updated figure in clause 6.2

-
-January 2024 -
-

1.7.7

-
-

From 168r1: 504 error instead of 503 in JSON-LD context endpoints

-

From 169r1: Allow forbidden characters

-

From 170: Remove Scope from PATCH /attrs operations

-

From 1005r2: URI for value of several attributes

-

From 173r2: Clarify match in distributed operations

-

From 174: Protect core context

-

From 25002r2: API Issue #10 Filter on value with specific datasetId

-
-January 2024 -
-

1.7.8

-
-

From 164r5: fix Tenant in Host Alias (164) and /info/sourceIdentity Endpoint + figure

-

Updated figure in clause 6.2

-

Updated figures in clause 4.2

-
-January 2024 -
-

1.7.9

-
-CIM(24)000007r2_Query_Language_Extension_for_Linked_Entity_Retrieval -
-January 2024 -
-

1.7.10

-
-Internal revision, cleanup -
-January 2024 -
-

1.7.10

-
-FIX: CIM(24)000015_Projection_attributes_error_messaging -
-January 2024 -
-

1.7.10

-
-FIX: CIM(24)000014r1_POST_Query_Parameters -
-January 2024 -
-

1.7.11

-
-TO revision -
-January 2024 -
-

1.7.12

-
-ISG CIM revision and cleanup after TO revision. New keywords -
-February 2024 -
-

1.7.13

-
-Footnotes in Tables -
-February 2024 -
-

1.7.15

-
-Change of NGSILDTerm style to HTML Keyboard -
-February 2024 -
-

1.7.16

-
-Added expiresAt to @context serving -
-March 2024 -
-

1.8.1

-
-Published -
-April 2024 -
-

1.8.2

-
-Clone of published -
-April 2024 -
-

1.8.3

-
-Minor typos and style cleanup -
-April 2024 -
-

1.8.3

-
-000048_Fix_operations_allowing_sysAttrs.docx -
-April 2024 -
-

1.8.3

-
-000047r2_Accept_header_in_case_of_partial_success__207_.docx -
-April 2024 -
-

1.8.3

-
-000049r1_Clarify__options__allowed_for_POST_queries.docx -
-April 2024 -
-

1.8.4

-
-Track changes removed -
-May 2024 -
-

1.8.5

-
-TooLargeResponse -
-June 2024 -
-

1.8.6

-
-CIM(24)000036r1_Loop_Detection -
-June 2024 -
-

1.8.7

-
-CIM(24)000033r6_Backwards_Compatibility_Indicators -
-June 2024 -
-

1.8.8

-
-CIM(24)000027r5_Value_Type -
-June 2024 -
-

1.8.9

-
-CIM(24)000029_Purge_Entities -
-June 2024 -
-

1.8.10

-
-CIM(24)000028r4_Transient_Entity_bugfixed -
-June 2024 -
-

1.8.11

-
-CIM(24)000070_Additional_Updates_to_ExpiresAt__Conformance_etc_ -
-October 2024 -
-

1.8.12

-
-CIM(24)000076r8_Entity_Maps_and_Split_Entities -
-October 2024 -
-

1.8.13

-
-CIM(24)000108_Adding_Missing_Elements_in_Core_Context_and_Data_Types.zip -
-October 2024 -
-

1.8.14

-
-Updated figures and new baseline and created Stable Draft out of this -
-November 2024 -
-

1.8.15

-
-CIM(24)000128r1_Signed_Attributes_and_Scoped_Context -
-December 2024 -
-

1.8.16

-
-VocabProperty instead of VocabularyProperty in C2.2 and Table 5.2.35‑1 -
-January 2025 -
-

1.8.17

-
-Reordering table rows in alpha (almost) order -
-January 2025 -
-

1.8.18

-
-Ngsildproof example and @context. Switching to new @context URI for v1.9 -
-February 2025 -
-

1.8.19

-
-CIM(25)000005 temporal bounds _clarifications_and_misc_fixes -
-March 2025 -
-

1.8.20

-
-CIM(24)000111r5_Ordered_Entites -
-March 2025 -
-

1.8.21

-
-CIM(24)000138r4_Snapshot -
-March 2025 -
-

1.8.22

-
-CLEAN. Removed all track changes. Comments to be still addressed -
-March 2025 -
-

1.8.23

-
-CIM(25)000011r1 Updated figures and text for Snapshots (clauses 5 and 6) -
-March 2025 -
-

1.8.24

-
-CIM(25)000012r1 Harmonize output and 203 -
-April 2025 -
-

1.8.25

-
-CIM(25)000014 GS_CIM_009_v1825_fixSubscriptions -
-April 2025 -
-

1.8.26

-
-CIM(25)000016 Explanation of valueType as data type -
-April 2025 -
-

1.8.27

-
-CIM(25)000015 Precision Clarification + Harmonize captions in clause 6 + addressing fixes requested in the comments -
-May 2025 -
-

1.8.28

-
-CIM(25)000023 Order Table rows + small editorial fixes + aggregation parameters for POST query -
-May 2025 -
-

1.8.29

-
-Final review prior to EditHelp -
-June 2025 -
-

1.8.30

-
-TO review: fuzzy figures, table numbering. Editorial: fixed core context and value in ngsildproof example -
- - diff --git a/API-html/22-history.html b/API-html/22-history.html deleted file mode 100644 index 51a9091c83b24f11681e58da0ea906dc1181144d..0000000000000000000000000000000000000000 --- a/API-html/22-history.html +++ /dev/null @@ -1,1544 +0,0 @@ - - - - - - - -History - - - - - - - - -

History

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Document history -
-V1.1.1 -
-January 2019 -
-Publication -
-V1.2.1 -
-October 2019 -
-Publication -
-V1.2.2 -
-February 2020 -
-Publication -
-V1.3.1 -
-August 2020 -
-Publication -
-V1.4.1 -
-February 2021 -
-Publication -
-V1.4.2 -
-April 2021 -
-Publication -
-V1.5.1 -
-November 2021 -
-Publication -
-V1.6.1 -
-August 2022 -
-Publication -
-V1.7.1 -
-June 2023 -
-Publication -
-V1.8.1 -
-March 2024 -
-Publication -
-V1.9.1 -
-June 2025 -
-Publication -
- - diff --git a/API-html/3-modal-verbs-terminology.html b/API-html/3-modal-verbs-terminology.html deleted file mode 100644 index 207d6be932cbb2ea208366b86dd87404f5b7613f..0000000000000000000000000000000000000000 --- a/API-html/3-modal-verbs-terminology.html +++ /dev/null @@ -1,1411 +0,0 @@ - - - - - - - -Modal verbs terminology - - - - - - - - -

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.

- - diff --git a/API-html/4-executive-summary.html b/API-html/4-executive-summary.html deleted file mode 100644 index 216a9b7b8f429255f9d5604fef79b6ee1603868c..0000000000000000000000000000000000000000 --- a/API-html/4-executive-summary.html +++ /dev/null @@ -1,1410 +0,0 @@ - - - - - - - -Executive summary - - - - - - - - -

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

- - diff --git a/API-html/5-introduction.html b/API-html/5-introduction.html deleted file mode 100644 index c19c5079cb6473fdcb189070f457532aafe4accb..0000000000000000000000000000000000000000 --- a/API-html/5-introduction.html +++ /dev/null @@ -1,1413 +0,0 @@ - - - - - - - -Introduction - - - - - - - - -

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.

- - diff --git a/API-html/6-tabscope.html b/API-html/6-tabscope.html deleted file mode 100644 index 4f929e26c2c924e481d003d558ff04719cb6ee29..0000000000000000000000000000000000000000 --- a/API-html/6-tabscope.html +++ /dev/null @@ -1,1410 +0,0 @@ - - - - - - - -1 Scope - - - - - - - - -

1 Scope

-

The present document defines a standardized 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].

- - diff --git a/API-html/7-tabreferences.html b/API-html/7-tabreferences.html deleted file mode 100644 index ce79f0f32b83e53e79c9b0c772adc75448800d4d..0000000000000000000000000000000000000000 --- a/API-html/7-tabreferences.html +++ /dev/null @@ -1,1619 +0,0 @@ - - - - - - - -2 References - - - - - - - - -

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 in the ETSI docbox.

-
-
-

NOTE:

-
-
-

While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity.

-
-
-

The following referenced documents are necessary for the application of the present document.

-
[1] W3C -® - Recommendation 25 February 2014: “ -RDF Schema 1.1 -”. -
[2] W3C -® - Recommendation 16 July 2020: “ -JSON-LD 1.1 - A JSON-based Serialization for Linked Data -”. -
[3] -IETF RFC 7231 -: “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”. -
[4] -IETF RFC 7232 -: “Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests”. -
[5] -IETF RFC 3986 -: “Uniform Resource Identifier (URI): Generic Syntax”. -
[6] -IETF RFC 8259 -: “The JavaScript Object Notation (JSON) Data Interchange Format”. -
[7] -IETF RFC 8288 -: “Web Linking”. -
[8] -IETF RFC 7946 -: “The GeoJSON Format”. -
[9] -IETF RFC 8141 -: “Uniform Resource Names (URNs)”. -
[10] -IETF RFC 7807 -: “Problem Details for HTTP APIs”. -
[11] -IEEE 1003.2™-1992 -: “IEEE Standard for Information Technology - Portable Operating System Interfaces (POSIX™) - Part 2: Shell and Utilities”. -
[12] -IETF RFC 5234 -: “Augmented BNF for Syntax Specifications: ABNF”. -
[13] -Unicode® Technical Standard #10 -: “Unicode Collation Algorithm”. -
[14] -Open Geospatial Consortium Inc. OGC 06-103r4 -: “OpenGIS -® - Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture”. -
[15] -Codes for Units of Measure used in International Trade Revision 9 -. -
[16] -IETF RFC 7396 -: “JSON Merge Patch”. -
[17] -ISO 8601: 2019 -: “Date and time — Representations for information interchange”. -
[18] -IETF RFC 2818 -: “HTTP Over TLS”. -
[19] -IETF RFC 5246 -: “The Transport Layer Security (TLS) Protocol Version 1.2”. -
[20] -IANA Registry of Link Relation Types -. -
[21] -ECMA-262 Specification -: “ECMAScript -® - 2022 language specification”. -
[22] The Unicode Consortium: “ -Unicode® 15.0.0 -”. -
[23] -IETF RFC 3987 -: “Internationalized Resource Identifiers (IRIs)”. -
[24] OASIS Standard: “ -MQTT Version 3.1.1 Plus Errata 01 -”. Edited by Andrew Banks and Rahul Gupta. 10 December 2015. -
[25] OASIS Standard: “ -MQTT Version 5.0 -”. Edited by Andrew Banks, Ed Briggs, Ken Borgendale and Rahul Gupta. 07 March 2019. -
[26] -IETF RFC 7240 -: “Prefer Header for HTTP”. -
[27] -IETF RFC 7230 -: “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”. -
[28] -IETF RFC 5646 -: “Tags for Identifying Languages”. -
[29] -IETF RFC 3282 -: “Content Language Headers”. -
[30] -IETF RFC 7234 -: “Hypertext Transfer Protocol (HTTP/1.1): Caching”. -
[31] -IETF RFC 7233 -: “Hypertext Transfer Protocol (HTTP/1.1): Range Requests”. -
[32] IANA: “ -Hypertext Transfer Protocol (HTTP) Warn Codes -”. -
[33] -IETF RFC 6906 -: “The ‘profile’ Link Relation Type”. -
[34] W3C -® - Recommendation 25 February 2014: “ -RDF 1.1 Concepts and Abstract Syntax -”. -
[35] -ETSI GS CIM 019 -: “cross-cutting Context Information Management (CIM); handling of provenance information in NGSI-LD”. -
[36] -IETF RFC 6067 -: “BCP 47 Extension U”. -
[37] -ETSI GS CIM 047 -: “Context Information Management (CIM); OpenAPI Specification for NGSI-LD API”. -
-

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.

-
-
-

NOTE:

-
-
-

While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity.

-
-
-

The following referenced documents may be useful in implementing an ETSI deliverable or add to the reader’s understanding, but are not required for conformance to the present document.

-
[i.1] -ETSI GR CIM 002 (V1.1.1) -: “Context Information Management (CIM); Use Cases (UC)”. -
[i.2] -ETSI GR CIM 007 -: “Context Information Management (CIM); Security and Privacy”. -
[i.3] -OMA-TS-NGSI_Context_Management-V1_0-20120529-A -: “NGSI Context Management”. -
[i.4] ETSI TS 103 264 (V3.1.1): “SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping”. -
[i.5] -NGSI-LD Wrapper -: “Experimental proxy for adaptation between FIWARE -® - and NGSI-LD”. -
[i.6] Graph Databases: “New Opportunities for Connected Data”. O’Reilly 2 -nd - Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892. -
[i.7] -JSON-LD Playground -: “Experimentation tool for JSON-LD”. -
[i.8] -ETSI GS CIM 006 -: “Context Information Management (CIM); Information Model (MOD0)”. -
[i.9] -FIWARE®-NGSI v2 Specification -. -
[i.10] -IETF RFC 6902 -: “JavaScript Object Notation (JSON) Patch”. -
[i.11] -JSON Schema Validation: A Vocabulary for Structural Validation of JSON -. -
[i.12] -OpenAPI™ Specification -. -
[i.13] -NGSI-LD JSON Schemas -. -
[i.14] -NGSI-LD OpenAPI™ Specification -. -
[i.15] -NGSI-LD Examples -. -
[i.16] ETSI GS CIM 004 (V1.1.2): “Context Information Management (CIM); Application Programming Interface (API)”. -
[i.17] ETSI ISG CIM: “ -NGSI-LD Status -”. -
[i.18] -Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016 - on the protection of natural persons with regard to the processing of personal data and on the free movement of such data, and repealing Directive 95/46/EC (General Data Protection Regulation). -
[i.19] -MQTT URI Scheme -. -
[i.20] -GeoJSON-LD 1.0 -. Base context for processing GeoJSON according to the JSON-LD processing model. -
[i.21] -ETSI GR CIM 008 -: “Context Information Management (CIM); NGSI-LD Primer”. -
[i.22] -IoT Agent Library -. -
- - diff --git a/API-html/8-tabdefinition-of-terms-symbols-and-abbreviations.html b/API-html/8-tabdefinition-of-terms-symbols-and-abbreviations.html deleted file mode 100644 index f73125e0b35f401401a528d2896037cda3076fb8..0000000000000000000000000000000000000000 --- a/API-html/8-tabdefinition-of-terms-symbols-and-abbreviations.html +++ /dev/null @@ -1,1675 +0,0 @@ - - - - - - - -3 Definition of terms, symbols and abbreviations - - - - - - - - -

3 Definition of terms, symbols and abbreviations

-

3.1 Terms

-

For the purposes of the present document, the following terms apply:

-
-
-

NOTE 1:

-
-
-

The letters “NGSI-LD” were added to most terms to confirm that they are distinct from other terms of similar/same name in use in other organizations, however, in the present document the letters “NGSI-LD” are generally omitted for brevity.

-
-
-
-
-

NOTE 2:

-
-
-

The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [23], which extends the use of characters to Unicode characters [22] beyond the ASCII character set, enabling the support of languages other than English.

-
-
-

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

-
-
-

NOTE:

-
-
-

It is used by Distribution Brokers and Federation Brokers to find the appropriate Context Sources which can provide the information required for serving an NGSI-LD request.

-
-
-

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

-
-
-

NOTE:

-
-
-

It is usually registered with an NGSI-LD Registry so that it can announce what kind of information it can provide, when requested, to Context Consumers and Brokers.

-
-
-

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

-
-
-

NOTE:

-
-
-

In the NGSI-LD API, any instance of such an entity is uniquely identified by a URI , and characterized by reference to one or more NGSI-LD Entity Type(s) .

-
-
-

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 Entity Type: categorization of an NGSI-LD Entity as belonging to a class of similar entities, or sharing a set of characteristic properties

-
-
-

NOTE:

-
-
-

In the NGSI-LD API, an NGSI-LD Entity Type is uniquely identified by a URI .

-
-
-
-
-

EXAMPLE 1:

-
-
-

“Vehicle” is an NGSI-LD Entity Type and is identified with a proper URI.

-
-
-
-
-

EXAMPLE 2:

-
-
-

Bob’s private car whose plate number is “ABCD1234” is an NGSI-LD Entity whose NGSI-LD Entity Type name is “Vehicle”.

-
-
-
-
-

EXAMPLE 3:

-
-
-

Alice’s motorhome has a unique URI as id, but can be assigned multiple NGSI-LD Entity types, e.g. “Vehicle” and “Home” .

-
-
-

NGSI-LD External Linked Entity: Linked Entity that is identified through a dereferenceable URI which does not exist within the current NGSI-LD system

-
-
-

NOTE:

-
-
-

It can exist within another NGSI-LD system or within a non-NGSI-LD system.

-
-
-
-
-

EXAMPLE:

-
-
-

An NGSI-LD Entity, whose Entity Type name is “Book” , can be externally linked, through the “wasWrittenBy” relationship, to a resource identified by the URI “http://dbpedia.org/resource/Mark_Twain” .

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

An NGSI-LD Entity, whose Entity Type name is “Vehicle”, can be internally linked, through the “isParkedAt” relationship, to another NGSI-LD Entity, of Type name “Parking” , identified by the URI “urn:ngsi-ld:Parking:Downtown1” .

-
-
-

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

-
-
-

NOTE:

-
-
-

The target value contains data which is not available for interpretation.

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“A bus route services the following bus stops” can be represented by an NGSI-LD ListRelationship whose name is “route” which holds an array of directed links towards a series of NGSI-LD Entities of type (Type name) “BusStop” .

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s vehicle is currently parked on a street which is known as ‘Grand Place’ in French and ‘Grote Markt’ in Dutch” can be represented by an NGSI-LD LanguageProperty whose name is “street” which holds an NGSI-LD Map of two key-value pairs containing both the French (“fr” ) and Dutch ( “nl” ) exonyms of the street name.

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s vehicle’s speed is 40 km/h” can be represented by an NGSI-LD Property, whose name is “speed”, and which characterizes an NGSI-LD Entity, whose NGSI-LD Type is “Vehicle” . Such a name can be expanded to a fully qualified name in the form of a URI , for instance “http://example.org/Vehicle” or “http://example.org/speed” .

-
-
-

NGSI-LD Query: collection of criteria used to select a sub-set of NGSI-LD Elements, 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

-
-
-

EXAMPLE 1:

-
-
-

An NGSI-LD Entity of type “Vehicle” can be the subject of an NGSI-LD Relationship whose object is an NGSI-LD Entity of type “Parking” .

-
-
-
-
-

EXAMPLE 2:

-
-
-

An NGSI-LD Entity of type “Vehicle” can be the subject of an NGSI-LD Relationship whose object is an array of NGSI-LD Entities of type “Passenger” .

-
-
-

NGSI-LD Scope: hierarchical structuring of Entities that enables restricting query results and notifications

-

NGSI-LD Snapshot: set of NGSI-LD Entities, retrieved through one or more NGSI-LD Queries, which are locally persisted, providing a relatively consistent view of the situation when the queries were executed, and on which Context Consumers can execute further local NGSI-LD Operations

-

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)

-
-
-

EXAMPLE:

-
-
-

Bob’s private car ‘speed’ NGSI-LD Value is the number 100 (kilometres per hour).

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s car is a non-commercial vehicle” can be represented by an NGSI-LD VocabProperty whose name is “category” which holds the string value “non-commercial” . If the associated JSON-LD context defines the term “non-commercial” as “http://example.com/non-commercial”, then the returned value shall be expanded using JSON-LD type coercion into the URI the “http://example.com/non-commercial” .

-
-
-

3.2 Symbols

-

Void.

-

3.3 Abbreviations

-

For the purposes of the present document, the following abbreviations apply:

-

ABNF Augmented Backus-Naur Form

-

ALG1 ALGorithm for transforming an NGSI-LD Entity into a JSON-LD document

-

AM Ante Meridiem

-

API Application Programming Interface

-

ASCII American Standard Code for Information Interchange

-

BNF Backus Naur Form

-

CH Switzerland

-

CSR Context Source Registration

-

ECMA European Computer Manufacturers Association

-

EU European Union

-

FI Future Internet

-

FQN Fully Qualified Name

-

GB Great Britain

-

GDPR General Data Protection Regulation

-

GeoJSON Geographic JavaScript Object Notation

-

GeoJSON-LD Geographic JavaScript Object Notation - Linked Data

-

GIS Geographic Information System

-

GPS Global Positioning System

-

HTTP Hypertext Transfer Protocol

-

HTTPS Hypertext Transfer Protocol Secure

-

IANA Internet Assigned Numbers Authority

-

ID IDentifier

-

IEEE Institute of Electrical and Electronics Engineers

-

IETF Internet Engineering Task Force

-

IoT Internet of Things

-

IRI Internationalized Resource Identifier

-

ISG Industry Specification Group

-

ISO International Organization for Standardization

-

JSON JavaScript Object Notation

-

JSON-LD JSON Linked Data

-

LD Linked Data

-

LWM2M LightWeight Machine to Machine

-

M2M Machine to Machine

-

MIME Multi-purpose Internet Mail Extensions

-

MQTT Message Queuing Telemetry Transport

-

N/A Not Applicable

-

NGSI Next Generation Service Interfaces

-

NGSILD Next Generation Service Interfaces Linked Data (same as NGSI-LD)

-

NID Namespace IDentifier

-

NSS Namespace Specific String

-

OAS Open API Specification

-

OMA Open Mobile Alliance

-

oneM2M oneM2M Partnership Project

-

PM Post Meridiem

-

POSIX Portable Operating System Interface

-

QoS Quality of Service

-

RDF Resource Description Format

-

REST REpresentational State Transfer

-

RFC Request For Comments

-

SAREF Smart Applications REFerence ontology

-

TCP Transport Control Protocol

-

TLS Transport Layer Security

-

TS Technical Specification

-

UCA Unicode Collation Algorithm

-

UL Ultra Light

-

UML Unified Modelling Language

-

URI Uniform Resource Identifier

-

URL Universal Resource Locator

-

URN Uniform Resource Name

-

UTC Coordinated Universal Time

-

UTF Unicode (or Universal Coded Character Set) Transformation Format

- - diff --git a/API-html/9-tabcontext-information-management-framework.html b/API-html/9-tabcontext-information-management-framework.html deleted file mode 100644 index ef27a0bb8a51d3e23c4040f32359c6d435bf21f8..0000000000000000000000000000000000000000 --- a/API-html/9-tabcontext-information-management-framework.html +++ /dev/null @@ -1,6923 +0,0 @@ - - - - - - - -4 Context Information Management Framework - - - - - - - - -

4 Context Information Management Framework

-

4.1 Introduction

-

The present 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.

-
-

-
-
-

Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure

-
-

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.

-
-

-
-
-

Legend:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-

-
-

[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.2-1: NGSI-LD Core Meta-Model

-
-

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

-
- -
-

4.2.3 Cross Domain Ontology

-
-

-
-
-

Legend:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-

-
-

[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: NGSI-LD Core Meta-Model plus the Cross-Domain 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:

-
- -
-

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

-
-

-
-
-

Figure 4.2.4-1: Cross-Domain Ontology and instantiation

-
-

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.

-
-

-
-
-

Figure 4.2.5-1: NGSI-LD information model as UML

-
-

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 NGSI-LD API implicitly defines two sets of Entities:

-
-
- -
-

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 clauses 4.3.3 and 4.3.4.

-
-

-
-
-

Figure 4.3.2-1: Centralized architecture

-
-

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.

-
-

-
-
-

Figure 4.3.3-1: Distributed architecture

-
-

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.

-
-

-
-
-

Figure 4.3.4-1: Federated architecture

-
-

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. To support the distributed and federated architectures described in clauses 4.3.3 and 4.3.4 respectively, distributed versions of the operations are needed. They are listed separately under Distributed API and require the operations of the Registry API. 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. The distributed versions of the operations are separately shown in Table 4.3.5‑1 under Distributed API, but there is a single clause for each of the operations describing both the centralized and distributed behaviour. In addition, the Distributed API has support operations only needed in distributed and federated architectures.

-
-

Table 4.3.5-1: NGSI-LD API structure

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-API -
-Functionality -
-Operations -
-

Core API

-
-

Context Information Provision - operations for providing or managing Entities and Attributes

-
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-
-Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system -
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-
-Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions -
-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.8.6 Notification

-
-

Temporal API

-
-Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entitiesand Attributes -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities -
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-
-Distributed API -
-Distributed Context Information Provision -operations for providing or managing Entities and Attributes -
-

5.6.1 Create Entity (distributed)

-

5.6.2 Update Attributes (distributed)

-

5.6.3 Append Attributes (distributed)

-

5.6.4 Partial Attribute Update (distributed)

-

5.6.5 Delete Attribute (distributed)

-

5.6.6 Delete Entity (distributed)

-

5.6.7 Batch Entity Creation (distributed)

-

5.6.8 Batch Entity Upsert (distributed)

-

5.6.9 Batch Entity Update (distributed)

-

5.6.10 Batch Entity Delete (distributed)

-

5.6.17 Merge Entity (distributed)

-

5.6.18 Replace Entity (distributed)

-

5.6.19 Replace Attribute (distributed)

-

5.6.20 Batch Entity Merge (distributed)

-
-Distributed Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system -
-

5.7.1 Retrieve Entity (distributed)

-

5.7.2 Query Entities (distributed)

-

5.7.5 Retrieve Available Entity Types (distributed)

-

5.7.6 Retrieve Details of Available Entity Types (distributed)

-

5.7.7 Retrieve Available Entity Type Information (distributed)

-

5.7.8 Retrieve Available Attributes (distributed)

-

5.7.9 Retrieve Details of Available Attributes (distributed)

-

5.7.10 Retrieve Available Attribute Information (distributed)

-
-Distributed Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions -
-

5.8.1 Create Subscription (distributed)

-

5.8.2 Update Subscription (distributed)

-

5.8.3 Retrieve Subscription (distributed)

-

5.8.4 Query Subscription (distributed)

-

5.8.5 Delete Subscription (distributed)

-

5.8.6 Notification (distributed)

-
-Distributed Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entities and Attributes -
-

5.6.11 Upsert Temporal Evolution of an Entity (distributed)

-

5.6.12 Add Attributes to Temporal Evolution of anEntity (distributed)

-

5.6.13 Delete Attributes from TemporalEvolution of an Entity (distributed)

-

5.6.14 Partial Update Attribute instance (distributed)

-

5.6.15 Delete Attribute Instance (distributed)

-

5.6.16 Delete Temporal Evolution of an Entity (distributed)

-
-Distributed Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities -
-

5.7.3 Retrieve Temporal Evolution of an Entity (distributed)

-

5.7.4 Query Temporal Evolution of Entities (distributed)

-
-Support operations for distributed operations -
-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMap for Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.15.1 Retrieve Context Source Identity Information

-
-

Registry API

-
-Context Source Registration- operations for registering Context Sourcesand managing Context Source Registrations(CSRs) -
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Context SourceDiscovery - operations for retrieving and discovering CSRs -
-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-
-Context Source RegistrationSubscription - operations for subscribing to CSRs, receiving notifications and managing CSRs -
-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-

5.11.7 CSR Notification

-
-Snapshot API -
-Operations for creating and managing Snapshots. -
-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-
-JSONLDContext API -
-Storing, managing and serving@contexts -
-

5.13.2 Add @context

-

5.13.3 List @contexts

-

5.13.4 Serve @context

-

5.13.5 Delete and Reload @context

-
-

All Context Brokers shall implement the Core API. Context Brokers supporting distributed and federated deployments shall also implement the Distributed 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 Snapshot API and the JSONLDContext API are optional. The managing and serving of @contexts can also be handled by an independent, stand-alone component.

-
-

Table 4.3.5-2: Main implementation configurations

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Description -
-Temporal API -
-RegistryAPI -
-Central Broker without temporal support -
-none -
-none -
-Central Broker with integrated temporal component -
-local -
-none -
-Central Broker with separate temporal component -
-separate -
-none -
-Context Broker supporting distributed and federated deployments without temporal support and with integrated Context Registry -
-none -
-local -
-Context Broker supporting distributed and federated deployments with integrated temporal component and integrated Context Registry -
-local -
-local -
-Context Broker supporting distributed and federated deployments with separate temporal component and integrated Context Registry -
-separate -
-local -
-Context Broker supporting distributed and federated deployments without temporal support and separate Context Registry -
-none -
-separate -
-Context Broker supporting distributed and federated deployments with integrated temporal component and separate Context Registry -
-local -
-separate -
-Context Broker supporting distributed and federated deployments with separate temporal component and separate Context Registry -
-separate -
-separate -
-

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 ContextBroker can implement all roles at the same time. Context Consumers typically only interact with ContextBrokers, 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.

-
-

Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-NGSI-LD Role -
-Implements -
-Uses -
-Context Consumer -
-

5.8.6 Notification - if supporting asynchronous interactions

-

In case of direct interactions with Context Registry:

-

5.11.7 CSR Notification -if supporting asynchronous interactions

-
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMap for Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.15.1 Retrieve Context Source Identity Information

-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-

In case of direct interactions with Context Registry:

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

if supporting asynchronous interactions:

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-Context Producer -
-none -
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-
-Context Source -
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMap for Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities5.15.1 Retrieve Context Source Identity Information

-
-

5.8.6 Notification

-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Context Repository -
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-
-none -
-Temporal Context Consumer -
-

In case of direct interactions with Context Registry:

-

5.11.7 CSR Notification - if supporting asynchronous interactions

-
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-

In case of direct interactions with Context Registry:

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

if supporting asynchronous interactions:

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-Temporal Context Producer -
-None -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-Temporal Context Source -
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Temporal Context Repository -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-none -
-Context Registry -
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-5.11.7 CSR Notification -
-

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

-

It is the responsibility of the Context Broker to respect the registration parameters when issuing distributed requests. For instance, if a registration states that only Entities of a given type are offered, the distributed request does not contain additional types. Such a strict requirement is justified because Context Sources (the receivers of the distributed request) are not in a position to determine whether a request has been triggered by a registration, rendering them unable to ensure that the registration parameters are respected in the first place. This applies for any kind of context data a Context Broker can exchange such as Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all constraints specified in the registration shall be respected.

-

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 everyContext 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:

-
- -
-

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 redirect Context Source Registration also specifies that the registered context data is held in a location external to the Context Broker. It is possible to register (any combination of):

-
-
- -
-

Potentially multiple distinct redirect registrations can apply at the same time. The Context Brokeritself 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 Sourceare 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 [27])) 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

-
-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration is present, it contains, whatever extra information the Context Broker shall convey when contacting the Context Source. This can be information the Context Broker needs to successfully communicate with the Context Source (e.g. Authorization material), or for the Context Source to correctly interpret the received content (e.g. the Link URL to fetch an @context). The method for conveying this information is binding-specific, e.g. using headers in the case of HTTP.

-
-
-

Instead of providing the actual value, the special value “urn:ngsi-ld:request” can be used to indicate that the respective value is to be taken from the request that triggered the given request, if present.

-
-
-
-

EXAMPLE:

-
-
-

If the key value pair “user”: “urn:ngsi-ld:request” is part of contextSourceInfo of the CSourceRegistration, the Context Broker checks if “user” was conveyed in the triggering request. If this is the case, e.g. “user”: “abcd” , “user”: “abcd” is also conveyed when contacting the 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

-
-

The following key-values have a specific well-defined meaning when defined as elements within the optional array contextSourceInfo of the CSourceRegistration.

-
-

If the key “accept” is defined:

-
- -
-

If the key “contentType” is defined:

-
- -
-

If the key “jsonldContext”is defined:

-
- -
-

If the key “ngsildConformance”is defined:

-
- -
-

4.3.6.7 Querying and Retrieving 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 process each Context Consumption request efficiently, and to support consistent pagination, it is necessary for the Context Broker to initially make a broad request to each registered Context Source whose registration is matching the request.

-

In the case of a query Entities operation (clause 5.7.2) or query Temporal Evolution of Entities operation (clause 5.7.4), a list of Entity identifiers is returned and stored together with the registration information in an Entity map. Only the Entities whose identifiers are contained in the Entity map are considered when rendering the result pages. Filtering based on queries, geoqueries, scope queries or attribute filters, as provided in the original query request, is applied to the Entities before adding the Entity to a result page, i.e. identifiers of Entities not matching the filters at the time of checking are removed from the Entity map.

-

In the case of a retrieve Entity operation (clause 5.7.1) or retrieve Temporal Evolution of an Entity operation (clause 5.7.3), an Entity map can be used to make subsequent retrievals of the same Entity more efficient, as the Entity map provides the information about which Context Source(s) store relevant Entity information, and other Context Sources do not have to be considered.

-

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 Table 6.4.3.2‑2) 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.

-

When executing Context Consumption or Subscription operations, a significant optimization in performance can be achieved if it is known a priori whether individual Entities are themselves distributed among Context Brokers and Context Sources, or if each Context Broker and Context Source always stores complete Entities. In the latter case all parameters used for filtering such as queries, geoqueries, scope queries or attribute filters can be forwarded and applied locally, whereas in the former case, the Entity first has to be assembled by the Context Broker and only then the filtering can be applied. Since being able to apply filters locally is significantly more efficient, a parameter can indicate that, for the given request, only Entities are to be expected that are stored in their entirety on each Context Broker and each Context Sources, and there are no Entities that are themselves stored in a distributed fashion. Such Entities are also referred to as split Entities. Context Broker implementations should enable configuring a default for this parameter, so deployments where no split Entities are to be expected can filter locally and thus be more efficient.

-

In the case of split Entities, EntityMaps initially only store “candidate Entities” as no filters could be applied, because only a part of the Entity was available. In the process of pagination, the filters will be (re-)checked. Any Entity not (or no longer) fulfilling the filter shall be removed from the EntityMap.

-

4.3.6.8 Backwards compatibility of Context Source payloads

-

When retrieving Entity data found distributed across multiple associated Context Brokers each Context Source is sent a context consumption request. A Context Broker shall assume that every Context Source will return valid NGSI-LD Entity data in a format that it understands and it shall reject data that is invalid. However, since the definition of a valid NGSI-LD Entity has broadened with each version of the NGSI-LD specification, it is possible that a registered Context Sourcecould respond with valid NGSI-LD Entity data which does not fit the narrower confines of a previous NGSI-LD specification.

-

Therefore, when making a context consumption request, a Context Broker may wish to indicate that it is only capable of interpreting responses which conform to a specific NGSI-LD specification, in which case the Context Sourceshall endeavour to amend its payload accordingly. Table 4.3.6.8‑1 describes a minimal level of support for a NGSI-LD Entity data as specified by each version of the NGSI-LD specification, and the expected fallback behaviour required if a context consumption request is made to receive data conformant to an earlier version of the NGSI-LD specification. Table 4.3.6.8‑2 describes conformance fallbacks for an NGSI-LD Property (and its subclasses) and Table 4.3.6.8‑2 describes conformance fallbacks for an NGSI-LD Relationship (and its subclasses).

-

The version of the NGSI-LD specification requested and the conformant version returned is defined in the form major.minor, for example 1.5.

-
-

Table 4.3.6.8-1: NGSI-LD Entity data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-

Version

-

Introduced

-
-Conformant Data Fallback -
-id -
-String -
-Valid URI -
-1.0 -
-
-type -
-String or String[] (see note 1) -
-1.0 -
-
-
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove attribute from payload -
-location -
-GeoProperty -
-Default geospatial Property of an entity. See clause 4.7 -
-1.0 -
-
-observationSpace -
-GeoProperty -
-See clause 4.7 -
-1.0 -
-
-operationSpace -
-GeoProperty -
-See clause 4.7 -
-1.0 -
-
-scope -
-String or String[] -
-See clause 4.18 -
-1.4 -
-Remove attribute from payload -
-<Property name> -
-Property or Property[] (see note 2) -
-Property as mandated by clause 4.5.2. -
-1.0 -
-
-GeoProperty or GeoProperty[] (see note 2) -
-GeoProperty as mandated by clause 4.5.2. -
-1.0 -
-
-LanguageProperty or LanguageProperty[] (see note 2) -
-LanguageProperty as mandated by clause 4.5.18. -
-1.4 -
-Reformat attribute as Property -
-JsonProperty or JsonProperty[] (see note 2) -
-JsonProperty as mandated by clause 4.5.24. -
-1.8 -
-Reformat attribute as Property -
-VocabProperty or VocabProperty[] (see note 2) -
-VocabProperty as mandated by clause 4.5.20. -
-1.8 -
-Reformat attribute as Property -
-ListProperty or ListProperty[] (see note 1) -
-ListProperty as mandated by clause 4.5.21. -
-1.8 -
-Reformat attribute as Property -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 3)

-
-Relationship as mandated by clause 4.5.3. -
-1.0 -
-
-ListRelationship or ListRelationship[] (see note 3) -
-ListRelationship as mandated by clause 4.5.22. -
-1.8 -
-Reformat attribute as Relationship -
-
-
-

NOTE 1:

-
-
-

From 1.3 onwards, an Entity type can be assigned multiple values. For 1.0 backwards compatibility only return a single element with preference to the first instance.

-
-
-
-
-

NOTE 2:

-
-
-

From 1.3 onwards, multiple instances of a Property (or subclass of Property ) identified by the same Property name can be separated by datasetId. For 1.0 backwards compatibility only return a single element of Property Array with preference to the default instance.

-
-
-
-
-

NOTE 3:

-
-
-

From 1.3 onwards, multiple instances of a Relationship (or subclass of Relationship ) identified by the same Relationship name can be separated by datasetId. From 1.3 onwards. For 1.0 backwards compatibility only return a single element of Relationship Array with preference to the default instance.

-
-
-
-
-

Table 4.3.6.8-2: NGSI-LD Property data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-Version Introduced -
-Conformant Data Fallback -
-type -
-String -
-1.0 -
-
-
-value -
-Any JSON value as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-1.0 -
-
-datasetId -
-String -
-Valid URI as mandated by clause 4.5.5 -
-1.3 -
-Remove attribute from payload -
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove attribute from payload -
-observedAt -
-String -
-DateTime as mandated by clause 4.8 -
-1.3 -
-Remove attribute from payload -
-unitCode -
-String -
-As mandated by [15] -
-1.3 -
-Remove attribute from payload -
-valueType -
-String -
-See clause 4.5.2 -
-1.9 -
-Remove attribute from payload -
-
-

Table 4.3.6.8-3: NGSI-LD Relationship data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-Version Introduced -
-Conformant Data Fallback -
-type -
-String -
-Valid URI -
-1.0 -
-
-object -
-String or String[] -
-1.0 -
-
-
-datasetId -
-String -
-Valid URI as mandated by clause 4.5.5 -
-1.3 -
-Remove attribute from payload -
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove attribute from payload -
-objectType -
-String or String[] -
-See clause 4.5.23 -
-1.8 -
-Remove attribute from payload -
-observedAt -
-String -
-DateTime as mandated by clause 4.8 -
-1.3 -
-Remove attribute from payload -
-

When responding to a context consumption request to supply data conforming to a specific NGSI-LD specification, Context Sources should indicate the version of the specification the returned payload actually conforms to. In general, Context Sources will not be expected to be flexible enough to supply payloads conformant to all past and future versions of the specification, but the requesting Context Broker may use supplied version information when collating data from multiple Context Sources. and to validate and amend received payloads.

-

4.3.7 Snapshots

-

Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables “freezing” the result by retrieving all results immediately and persisting them locally. Context Consumers can then query and analyse the Snapshot in a much more consistent way.

-

This is especially relevant for distributed cases, where information initially was distributed across multiple Context Brokers and Context Sources.

-

Snapshots offer the full functionality of NGSI-LD available locally and can be used as a basis for simulations that enable making predictions or “what-if” analyses, which are often needed for digital twins.

-

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:

-
- -
-

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.9.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:

-
- -
-
- -
-
- -
-
- -
-

Whereas the Core NGSI-LD @context contains JSON-LD Scoped Contexts, the user @context shall not contain JSON-LD Scoped Contexts (see [2], ), as described in clause 5.5.7, because this would enable overwriting terms defined in the Core NGSI-LD @context.

-

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. If an array is required, an array with one single NGSI-LD Null is used. 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

-
- -
-

Optional

-
- -
-
-
-

NOTE 1:

-
-
-

In the following, the term Attribute is used when referring in the text to both a Property and a Relationship (see definition of NGSI-LD Attribute in clause 3.1 ).

-
-
-
-
-

NOTE 2:

-
-
-

When GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.16 for details.

-
-
-

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

- -
-

It should be noted that in the JSON-LD serialization, a number data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker’s internal representation, a number is equivalent to either an integer or floating-point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating-point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process.

-
-

Optional

-
- -
-

System Generated

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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). If the provided value is a JSON object and contains a ”type” field, the whole Attribute shall be treated as a normalized representation (see clause 4.5.2.2).

-

An NGSI-LD Property which includes 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) which includes the following members:

-

Mandatory

-
- -
-
-

It should be noted that in the JSON-LD serialization, a number data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker’s internal representation, a number is equivalent to either an integer or floating-point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating-point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process.

-
-

Optional

-
- -
-

System Generated

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-

System Generated

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-

System Generated

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-
-
-

EXAMPLE 1:

-
-
-

“name”: “David Robert Jones”

-
-
-
- -
-
-
-

EXAMPLE 2:

-
-
-
-
-

“name”: {

-

  “dataset”: {

-

    “@none”: “David Robert Jones”,

-

    “urn:ngsi-ld:datasetId:001”: “David Bowie”,

-

    “urn:ngsi-ld:datasetId:002”: “Ziggy Stardust”

-

  }

-

}

-
- -
-
-
-

EXAMPLE 3:

-
-
-

“location”: {“type”: “Point”, “coordinates”: [13.3986, 52.5547]}

-
-
-
- -
-
-
-

EXAMPLE 4:

-
-
-

“says”: {“languageMap”: {“en”: “yes”, “fr”: “oui”}

-
-
-
- -
-
-
-

EXAMPLE 5:

-
-
-
-
-

“parkingTickets”: {

-

  “json”: {

-

     “id”: “85a6cc52-0589-45f9”,

-

     “value”: “Overstay 60 minutes”

-

  }

-

}

-
- -
-
-
-

EXAMPLE 6:

-
-
-

“gender”: {“vocab”: “Male”}

-
-
-
- -
-
-
-

EXAMPLE 7:

-
-
-

” providedBy”: “urn:ngsi-ld:Device:31415”

-
-
-
-
-

EXAMPLE 8:

-
-
-
-
-

[“devices”: 

-

  “urn:ngsi-ld:Device:14142”,

-

     “urn:ngsi-ld:Device:13562”, 

-

     “urn:ngsi-ld:Device:37309”

-

[]]{.HTML_Sample}

-
- -
-
-
-

EXAMPLE 9:

-
-
-
-
-

“providedBy”: {

-

“id”: “urn:ngsi-ld:Device:31415”,

-

“type”: “Device”,

-

”brandName“: ”Anemometer“,

-

“manufacturerName”: “Cyberdyne Systems”,

-

”windSpeed“: 60

-

}

-
-
-

EXAMPLE 10:

-
-
-
-
-

[“devices”: 

-

  {

-

       “id”: “urn:ngsi-ld:Device:14142”,

-

       “type”: “Device”,

-

       “brandName”: “Anemometer”,

-

       “manufacturerName”: “Cyberdyne Systems”,

-

 “windSpeed”: 60

-

    },

-

    {

-

       “id”: “urn:ngsi-ld:Device:13562”,

-

       “type”: “Device”,

-

       “brandName”: “Hygromometer”,

-

       “manufacturerName”: “Acme Corporation”,

-

       “humidity”: 64

-

    },

-

    { 

-

       “id”: “urn:ngsi-ld:Device:37309”,

-

       “type”: “Device”,

-

       “brandName”: “Barometer”,

-

       “manufacturerName”: “Trask Industries”,

-

    “pressure”: 760

-

    }

-

[]]{.HTML_Sample}

-
- -
-
-
-

EXAMPLE 11:

-
-
-
-
-

[

-

  {

-

…etc

-

”providedBy“: ”urn:ngsi-ld:Device:31415”

-

  },

-

{

-

 “id”: “urn:ngsi-ld:Device:31415”,

-

 “type”: “Device”,

-

 “brandName”: “Anemometer”,

-

 “manufacturerName”: “Cyberdyne Systems”,

-

 “windSpeed”: 60

-

}

-

[]]{.HTML_Sample}

-
-
-

EXAMPLE 12:

-
-
-
-
-

[

-

    {

-

      … etc

-

[      “providedBy”: 

-

   “urn:ngsi-ld:Device:14142”, 

-

         “urn:ngsi-ld:Device:13562”, 

-

         “urn:ngsi-ld:Device:37309”

-

[       ]]{.HTML_Sample}

-

    },

-

    {

-

       “id”: “urn:ngsi-ld:Device:14142”,

-

       “type”: “Device”,

-

       “brandName”: “Anemometer”,

-

       “manufacturerName”: “Cyberdyne Systems”,

-

       “windSpeed”: 60

-

    },

-

    {

-

       “id”: “urn:ngsi-ld:Device:13562”,

-

       “type”: “Device”,

-

       “brandName”: “Hygromometer”,

-

       “manufacturerName”: “Acme Corporation”,

-

       “humidity”: 64

-

    },

-

    {

-

       “id”: “urn:ngsi-ld:Device:37309”,

-

       “type”: “Device”,

-

       “brandName”: “Barometer”,

-

       “manufacturerName”: “Trask Industries”,

-

       “pressure”: 760

-

    }

-

[]]{.HTML_Sample}

-
- -
-
-
-

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”

-

}

-

}

-
- -
-
-
-

EXAMPLE 14:

-
-
-

“periods”: [“First”, “Second”, “Third”, “Fourth”]

-
-
-
- -
-
-
-

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”]

-

}

-

}

-
- -
-
-
-

EXAMPLE 16:

-
-
-
-
-

[“route”:

-

“urn:ngsi-ld:BusStop:0101”,

-

“urn:ngsi-ld:BusStop:0102”,

-

“urn:ngsi-ld:BusStop:9912”

-

[]]{.HTML_Sample}

-
- -
-
-
-

EXAMPLE 17:

-
-
-
-
-

[“route”: 

-

{

-

“id”: “urn:ngsi-ld: BusStop:0101”,

-

“type”: “BusStop”,

-

“stopName”: “High Street”,

-

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

-

},

-

{

-

“id”: “urn:ngsi-ld: BusStop:0102”,

-

“type”: “BusStop”,

-

“stopName”: “Station Road”, 

-

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

-

},

-

{

-

“id”: “urn:ngsi-ld: BusStop:9912”,

-

“type”: “BusStop”,

-

“stopName”: “Mornington Cresent”, 

-

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

-

}

-

[]]{.HTML_Sample}

-
- -
-
-
-

EXAMPLE 18:

-
-
-
-
-

[

-

  {

-

    …etc

-

[    “route”: 

-

“urn:ngsi-ld:BusStop:0101”,

-

“urn:ngsi-ld:BusStop:0102”,

-

“urn:ngsi-ld:BusStop:9912”

-

[]]{.HTML_Sample}

-

  },

-

  {

-

“id”: “urn:ngsi-ld: BusStop:0101”

-

“type”: “BusStop”,

-

“stopName”: “High Street”, 

-

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

-

  {

-

    “id”: “urn:ngsi-ld: BusStop:0102”,

-

 “type”: “BusStop”,

-

“stopName”: “Station Road”, 

-

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

-

  },

-

  {

-

“id”: “urn:ngsi-ld:BusStop:9912”

-

“type”: “BusStop”,

-

“stopName”: “Mornington Cresent”, 

-

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

-

  }

-

[]]{.HTML_Sample}

-
- -
-
-
-

EXAMPLE 19:

-
-
-
-
-

“route”: {

-

“dataset”: {

-

[    “@none”: 

-

“urn:ngsi-ld:BusStop:0101”,

-

“urn:ngsi-ld:BusStop:0102”,

-

“urn:ngsi-ld:BusStop:9912”

-

[],]{.HTML_Sample}

-

“urn:ngsi-ld:datasetId:001”: [

-

“urn:ngsi-ld:BusStop:0101”,

-

“urn:ngsi-ld:BusStop:0102”,

-

“urn:ngsi-ld:BusStop:0022”

-

[],]{.HTML_Sample}

-

[     “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”

-

[]]{.HTML_Sample}

-

}

-

}

-
-
-

NOTE:

-
-
-

When the simplified GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.17 for details.

-
-
-

4.5.5 Multi-Attribute Support

-

4.5.5.1 Introduction

-

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 datasetIdcan 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, expiresAt and observedAt, and also the unitCode Property.

-

4.5.5.2 Processing of Conflicting Transient Entities

-

In case of conflicting information when an Entity is received from a registered Context Sourceand marked with an expiresAt DateTime, but this expiresAt is not duplicated across all versions of the Entity received across all registered Context Sources, the following mechanism shall be used to differentiate.

-

For each version of the Entity received where the expiresAt non-reified attribute is present at the Entity level:

-
- -
-

4.5.5.3 Processing of Conflicting Attributes

-

In case of conflicting information for an Attribute, where a datasetId is duplicated, but there are differences in the other attribute data, if an expiresAt DateTime is present on the Attribute and the date lies in the past, it shall be discarded, thereafter 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.

-

When conflicting information is received for the non-reified expiresAt attribute at an Entity level:

-
- -
-

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 (or a single JSON-LD object in case only one is present), 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 [i.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 a 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 (or a single JSON-LD object in case only one is present), 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 [i.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 ofEntities, 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

-
- -
-

Optional

-
- -
-
-
-

EXAMPLE 1:

-
-
-
"name": {
-  "type": "Property",
-  "values": [
-    [
-      "Joe Bloggs",
-      "2022-08-09T18:25:02Z"
-    ],
-    [
-      "Bill Smith",
-      "2022-08-10T18:25:02Z"
-    ]
-  ]
-}
-
-
-
- -
-
-
-

EXAMPLE 2:

-
-
-
-
-

“says”: {

-

“type”: “LanguageProperty”,

-

[  “languageMaps”: 

-

[    

-

{“languageMap”: {“en”: “yes”, “fr”: “oui”}},

-

“2022-08-09T18:25:02Z”

-

[],]{.HTML_Sample}

-

[    

-

{“languageMap”: {“en”: “no”, “fr”: “non”}},

-

“2022-08-10T18:25:02Z”

-

[]]{.HTML_Sample}

-

[]]{.HTML_Sample}

-

}

-
- -
-
-
-

EXAMPLE 3:

-
-
-
-
-

“period”: {

-

  “type”: “ListProperty”,

-

[  “valueLists”: 

-

[    

-

      [“First”, “Second”, “Third”, “Fourth”],

-

      “2022-08-09T18:25:02Z”

-

[    ],]{.HTML_Sample}

-

[    

-

      [“1st”, “2nd”, “3rd”, “4th”],

-

      “2022-08-10T18:25:02Z”

-

[    ]]{.HTML_Sample}

-

[  ]]{.HTML_Sample}

-

}

-
- -
-
-
-

EXAMPLE 4:

-
-
-
-
-

“parkingTickets”: {

-

“type”: “JsonProperty”,

-

[  “jsons”: 

-

[    

-

{

-

[        “json”:  

-

          {

-

            “id”: “85a6cc52-0589-45f9”,

-

            “value”: “Overstay 60 minutes”

-

          }

-

[        ],]{.HTML_Sample}

-

      },

-

“2022-08-09T18:25:02Z”

-

[],]{.HTML_Sample}

-

[    

-

{

-

[        “json”: 

-

          {

-

            “id”: “85a6cc52-0589-45f9”,

-

            “value“: ”Overstay 60 minutes”

-

          },

-

          {

-

            “id”: “x5c56s-0589-45f9”,

-

            “value”: “Overstay 45 minutes”

-

          }

-

[        ]]{.HTML_Sample}

-

      },

-

“2022-08-10T18:25:02Z”

-

[]]{.HTML_Sample}

-

[]]{.HTML_Sample}

-

}

-
- -
-
-
-

EXAMPLE 5:

-
-
-
-
-

“gender”: {

-

“type”: “VocabProperty”,

-

[  “vocabs”: 

-

[    

-

{“vocab”: “Male”},

-

“2022-08-09T18:25:02Z”

-

[],]{.HTML_Sample}

-

[    

-

{“vocab”: “Female”},

-

“2022-08-10T18:25:02Z”

-

[]]{.HTML_Sample}

-

[]]{.HTML_Sample}

-
-

}

-
-
- -
-
-
-

EXAMPLE 6:

-
-
-
-
-

“spouse”: {

-

  “type”: “Relationship”,

-

[  “objects”: 

-

[    

-

      “urn:ngsi-ld:Person:123455”,

-

      “2022-08-09T18:25:02Z”

-

[    ],]{.HTML_Sample}

-

[    

-

      “urn:ngsi-ld:Person:999999”,

-

      “2022-08-10T18:25:02Z”

-

[    ]]{.HTML_Sample}

-

[  ]]{.HTML_Sample}

-

}

-
-
-

EXAMPLE 7:

-
-
-
-
-

“activeDevices”: {

-

  “type”: “Relationship”,

-

[  “objects”: 

-

[    

-

      [“urn:ngsi-ld:Device:14142”, “urn:ngsi-ld:Device:13562”],

-

      “2022-08-09T18:25:02Z”

-

[],]{.HTML_Sample}

-

[    

-

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

-

      “2022-08-10T18:25:02Z”

-

[]]{.HTML_Sample}

-

[  ]]{.HTML_Sample}

-

}

-
- -
-
-
-

EXAMPLE 7:

-
-
-
-
-

“membersPresent”: {

-

  “type”: “ListRelationship”,

-

[  “objectLists”: 

-

[    

-

      [“urn:ngsi-ld:Person:Alice”, “urn:ngsi-ld:Person:Bob”],

-

      “2022-08-09T18:25:02Z”

-

[    ],]{.HTML_Sample}

-

[    

-

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

-

      “2022-08-10T18:25:02Z”

-

[    ]]{.HTML_Sample}

-

[  ]]{.HTML_Sample}

-

}

-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-
- -
-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

-
- -
-
- -
-

Optional

-
- -
-

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

-
- -
-

Optional

-
- -
-

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

- -

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

- -

Optional

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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:

-
- -
-

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

-
- -
-
- -
-
-
    -
  1. the value obtained after applying the aggregation method over the period;
    2. -
-
-
-
    -
  1. the start DateTime of the corresponding period;
    2. -
-
-
-
    -
  1. the end DateTime of the corresponding period.
    2. -
-
-
- -
-
-
    -
  1. the value obtained after applying the aggregation method over the period;
    2. -
-
-
-
    -
  1. the start DateTime of the corresponding period;
    2. -
-
-
-
    -
  1. the end DateTime of the corresponding period.
    2. -
-
-

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:

-
- -
-

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

-
- -
-

The values supported by the aggrMethods parameter are the following:

-
- -
-

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

-
-

Table 4.5.19.1-1: Semantics of aggregation methods for Properties on JSON native data types

-
- -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Aggregation Method -
-JSON String -
-JSON Number -
-JSON Object -
-JSON Array -
-

JSON Boolean

-

(see note)

-
-avg -
-N/A -
-Calculate the average of the values inside the period -
-N/A -
-Calculate the average number of the sizes of the arrays inside the period -
-Calculate the average of the values inside the period -
-distinctCount -
-Calculate the count of distinct values inside the period -
-max -
-Calculate the last value in lexicographical order inside the period -
-Calculate the maximum value inside the period -
-N/A -
-Calculate the maximum size of the arrays inside the period -
-Calculate the maximum value inside the period -
-min -
-Calculate the first value in lexicographical order inside the period -
-Calculate the minimum value inside the period -
-N/A -
-Calculate the minimum size of the arrays inside the period -
-Calculate the minimum value inside the period -
-stddev -
-N/A -
-Calculate the standard deviation of the values inside the period -
-N/A -
-N/A -
-Calculate the standard deviation of the values inside the period -
-sum -
-N/A -
-Calculate the sum of the values inside the period -
-N/A -
-Calculate the sum of the sizes of the arrays inside the period -
-Calculate the sum of the values inside the period -
-sumsq -
-N/A -
-Calculate the sum of the square of the values inside the period -
-N/A -
-N/A -
-Calculate the sum of the square of the values inside the period -
-totalCount -
-Calculate the number of times the value has been updated inside the period -
-
-
-

NOTE:

-
-
-

For the purpose of aggregation, true is considered as a value of 1, false is considered as a value of 0.

-
-
-
-
-

Table 4.5.19.1-2: Semantics of aggregation methods for Properties on other supported data types

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Aggregation Method

-
-

DateTime

-
-

Date

-
-

Time

-
-

URI

-
-avg -
-N/A -
-N/A -
-Calculate the average time inside the period (e.g. to apply on an event that occurs at non fixed times, like the time a car enters a given parking) -
-N/A -
-distinctCount -
-Calculate the count of distinct values inside the period -
-max -
-Calculate the maximum value inside the period -
-Calculate the maximum value inside the period -
-Calculate the maximum value inside the period -
-N/A -
-min -
-Calculate the minimum value inside the period -
-Calculate the minimum value inside the period -
-Calculate the minimum value inside the period -
-N/A -
-stddev -
-N/A -
-N/A -
-N/A -
-N/A -
-sum -
-N/A -
-N/A -
-N/A -
-N/A -
-sumsq -
-N/A -
-N/A -
-N/A -
-N/A -
-totalCount -
-Calculate the number of times the value has been updated inside the period -
-
-

Table 4.5.19.1-3: Semantics of aggregation methods for Relationships

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Aggregation Method

-
-

Relationship

-
-avg -
-

N/A

-
-distinctCount -
-

Calculate the count of distinct relationships targets inside the period

-
-max -
-

N/A

-
-min -
-

N/A

-
-stddev -
-

N/A

-
-sum -
-

N/A

-
-sumsq -
-

N/A

-
-totalCount -
-

Calculate the number of times the relationship has been updated inside the period

-
-

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

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-
-

An array consisting of a single 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 “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

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-
-

An array consisting of a single 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 “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

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-
-

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

-
-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-
- -
-
-

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

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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.

-
-

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

-
-

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

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-

Output Only

-
- -
-

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

-

Prohibited

-
- -
-

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

-
- -
-

Optional

-
- -
-

Output Only

-
- -
-

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:

-
nameChar = unicodeNumber / unicodeLetter
-nameChar =/ %x5F                  ; _
-name = unicodeLetter *nameChar
-
- -
-

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

-
prefix = unicodeLetter *nameChar
-name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name
-

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:

-
- -
-
- -
-
-
-

NOTE 1:

-
-
-

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used .

-
-
-
- -
-
- -
-
- -
-
- -
-
- -
-
-
-

NOTE 2:

-
-
-

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used.

-
-
-
- -
-
- -
-

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

-
- -
-

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:

-
- -
-

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:

-
- -
-

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:

-
- -
-

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.

-
-

GeoJSON coordinates shall be considered as consisting of values of a JSON-LD floating point number data type. The degree of precision of a latitude and longitude (and optional altitude) held within a context broker will depend upon the implementation. Implementors should note that the GeoJSON specification itself recommends 6 decimal places for latitude and longitude which equates to roughly 10cm of precision.

-
-

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

-
- -
-

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:

-
- -
-

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

-
-
-

NOTE 1:

-
-
-

For simplicity reasons, a TemporalProperty is represented only by its Value, i.e. no Properties of TemporalProperty nor Relationships of TemporalProperty can be conveyed. In more formal language, a TemporalProperty does not allow reification.

-
-
-
-
-

NOTE 2:

-
-
-

It is important to remark that the term TemporalProperty has been reserved for the semantic tagging of non-reified structural timestamps ( observedAt , createdAt , modifiedAt, deletedAt , expiresAt ), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as timeproperty in Temporal Queries as mandated by clause 4.11 .

-
-
-
-
-

NOTE 3:

-
-
-

User-defined Properties whose value is a time value ( Date, DateTime or Time ) are defined as Property , not as TemporalProperty , and are serialized in NGSI-LD as shown in annex C, clause C.6 .

-
-
-

Whenever a TemporalProperty value is unknown by a registered Context Source, the Property shall be omitted rather than sending an error response.

-

4.9 NGSI-LD Query Language

-

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

-
- -
-

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

-
- -
-

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://github.com/ietf-tools/bap>), and it shall be supported by implementations:

-
Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm /
-QueryTermAssoc))
-QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ;
-(QueryTerm)
-QueryTerm = Attribute
-QueryTerm =/ Attribute Operator ComparableValue
-QueryTerm =/ Attribute equal CompEqualityValue
-QueryTerm =/ Attribute unequal CompEqualityValue
-QueryTerm =/ Attribute patternOp RegExp
-QueryTerm =/ Attribute notPatternOp RegExp
-Attribute = LinkedEntityRelation
-LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D          ;
-AttrName{LinkedEntityPath}
-LinkedEntityRelation =/ ValuePath
-LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B
-LinkedEntityPath %x7D
-;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath}
-LinkedEntityPath =/ ValuePath
-ValuePath = DottedPath *1(%x5B DottedPath %x5D)                     ; DottedPath
-*1([DottedPath])
-DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName)
-Operator = equal / unequal / greaterEq / greater / lessEq / less
-ComparableValue = Number / quotedStr / dateTime / date / time
-OtherValue = false / true
-Value = ComparableValue / OtherValue
-Range = ComparableValue dots ComparableValue
-ValueList = Value 1*(%x2C Value) ; Value 1*(, Value)
-CompEqualityValue = OtherValue / ValueList / Range / URI
-equal = %x3D %x3D ; ==
-unequal = %x21 %x3D ; !=
-greater = %x3E ; >
-greaterEq = %x3E %x3D ; >=
-less = %x3C ; <
-lessEq = %x3C %x3D ; <=
-patternOp = %x7E %x3D ; ~=
-notPatternOp = %x21 %x7E %x3D ; !~=
-dots = %x2E %x2E ; ..
-TermChar = unicodeNumber / unicodeLetter
-TermChar =/ %x5F ; _
-AttrName = unicodeLetter *TermChar
-EntityType = unicodeLetter *TermChar
-quotedStr = String ; "*char"
-andOp = %x3B ; ;
-orOp = %x7C ; |
-LogicalOp = andOp / orOp
-
- -
-

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:

-
- -
-

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.

-
-
-

EXAMPLE 0:

-
-
-

?q=temperature (checks for the existence of the attribute temperature).

-
-
-
-
-

EXAMPLE 1:

-
-
-

?q=temperature==20 .

-
-
-
-
-

EXAMPLE 2:

-
-
-

?q=brandName!=“Mercedes” .

-
-
-
-
-

EXAMPLE 3:

-
-
-

?q=isParked==“urn:ngsi-ld:OffStreetParking:Downtown1” .

-
-
-
-
-

EXAMPLE 4:

-
-
-

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 . The NGSI-LD query language string is conveyed by means of parameter q .

-
-
-
-
-

EXAMPLE 5:

-
-
-

?q=isMonitoredBy (to query Entities that have the Attribute isMonitoredBy ).

-
-
-

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

-
- -
-

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.

-
-
-

EXAMPLE 6:

-
-
-

?q=((speed>50|rpm>3000);brandName==“Mercedes”)

-
-
-
-
-

EXAMPLE 7:

-
-
-

?q=(temperature>=20;temperature<=25)|capacity<=10

-
-
-

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:

-
- -
-
-
-

EXAMPLE 8:

-
-
-

?q=temperature.observedAt>=2017-12-24T12:00:00Z

-
-
-

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.

-
-
-

EXAMPLE 9:

-
-
-

?q=address[city]==“Berlin” . The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property , which is a complex JSON object representing a postal address. Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:placedescription:123",
-  "type": "PlaceDescription",
-  "address": {
-    "type": "Property",
-    "value": {
-      "city": "Berlin",
-      "street": "Ulrich Strasse"
-    }
-  }
-}
-
-
-
-
-

EXAMPLE 10:

-
-
-

?q=sensor.rawdata[airquality.particulate]==40 . The trailing path is [airquality.particulate]. The particulate Property of the compound JSON object is targeted. Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:particulatemeasurement:345",
-  "type": "ParticulateMeasurement",
-  "sensor": {
-    "type": "Property",
-    "value": 40,
-    "rawdata": {
-      "type": "Property",
-      "value": {
-        "airquality": {
-          "particulate": 40,
-          "PM20": 85
-        }
-      }
-    }
-  }
-}
-
-
-
-
-

EXAMPLE 11:

-
-
-

?q=parkingTickets[value]==“Overstay 60 minutes”&jsonKeys=parkingTickets . The trailing path is parkingTickets . The parkingTickets Property of the JSON object is targeted, but the target value raw is JSON, and is not expanded to ngsi-ld:hasValue using the core @context . Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:Car:6152s",
-  "type": "Car",
-  "parkingTickets": {
-  "type": "JsonProperty",
-  "json": {
-         "id": "85a6cc52-0589-45f9",
-         "value": "Overstay 60 minutes"
-      }
-  }
-}
-
-
-
-
-

EXAMPLE 12:

-
-
-

?q=gender==Male&expandValues=gender . The trailing path is gender . The gender Property of JSON object is targeted, but the target value is first expanded to a URI using the supplied @context . Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:Person:678",
-  "type": "Person",
-  "gender": {
-    "type": "VocabProperty",
-    "vocab": "Male",
-    }
-  },
-  @context": {
-    "Male": "http://example.org/Male",
-  }
-}
-
-
-

The filter can also apply to a Property or Relationship of an NGSI-LD Entity targeted by a (recursively) followed Relationship, for example as part of a linked entity retrieval (clause 4.5.23).

-
-
-

EXAMPLE 13:

-
-
-

?q=sensor{humidity}==40 . The trailing path is sensor{humidity} . The query targets entities with a sensor Relationship and makes a sub-query on matching target objects which have the matching humidity Attribute. Refer to the following NGSI-LD Entities:

-
{
-  "id": "urn:ngsi-ld:WeatherStation:123",
-  "type": "WeatherStation",
-  "sensor": {
-    "type": "Relationship",
-     "objectType": "Device",
-    "object": "urn:ngsi-ld:Device:345"
-  }
-}
-{
-  "id": "urn:ngsi-ld:Device:345",
-  "type": "Device",
-  "humidity": {
-    "type": "Property",
-    "value": 40
-  }
-}
-
-
-

As not knowing the Entity Type targeted by a Relationship could make the query significantly more expensive, a hint for the required Entity Type can be provided, so only such NGSI-LD Entities need to be considered.

-
-
-

EXAMPLE 14:

-
-
-

?q=sensor{Device:humidity}==40 . The trailing path is sensor{Device:humidity} . The query targets entities with a sensor.entityType = “Device” within a Relationship and then makes a sub-query on matching target objects which have the matching humidity Attribute. The entityType hint results in a faster lookup. Refer to the following NGSI-LD Entities.

-
{
-  "id": "urn:ngsi-ld:WeatherStation:123",
-  "type": "WeatherStation",
-  "sensor": {
-    "type": "Relationship",
-  "objectType": "Device",
-    "object": "urn:ngsi-ld:Device:345"
-  }
-}
-{
-  "id": "urn:ngsi-ld:Device:345",
-  "type": "Device",
-  "humidity": {
-    "type": "Property",
-    "value": 40
-  }
-}
-
-
-

If the target element corresponds to a Relationship or ListRelationship, the combination of such target element with any operator different than equal or unequal shall result in not matching.

-

A Query Term value shall be any of the following (depending on the operator used):

-
- -
-

When comparing dates or times, the order relation considered shall be a temporal one.

-

When it comes to comparing text strings, implementations:

-
- -
-

URI comparison should be performed so that the number of false negatives is minimized, as recommended by IETF RFC 3986 [5], section 6.

-

The semantics of the different logical operators used by Query Terms are described as follows and shall be supported by compliant implementations:

-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-

4.10 NGSI-LD Geoquery Language

-

The NGSI-LD Geoquery language shall be supported by implementations. It is intended to define predicates which allow testing whether a specific topological spatial relationship exists between a pair of geometries: a target geometry and a reference geometry. The target geometry represents a geospatial Property of an Entity, typically, the location of the Entity.

-

A total of four parameters are defined in order to fully specify an NGSI-LD Geoquery:

-
- -
-

The following grammar defines the syntax for the geospatial relationships (parameter name georel):

-
andOp = %x3B ; ;
-equal = %x3D %x3D ; ==
-georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel
-/ equalsRel / disjointRel
-nearRel = nearOp andOp distance equal PositiveNumber ;
-near;max(min)Distance==x (in meters)
-distance = "maxDistance" / "minDistance"
-nearOp = "near"
-withinRel = "within"
-containsRel = "contains"
-intersectsRel = "intersects"
-equalsRel = "equals"
-disjointRel = "disjoint"
-overlapsRel = "overlaps"
-

PositiveNumber shall be a non-zero positive number as mandated by the JSON Specification. Thus, it shall follow the ABNF Grammar, production rule named Number, section 6 of IETF RFC 8259 [6], excluding the ‘minus’ symbol and excluding the number 0.

-

Reference geometries shall be specified by:

-
- -
-

Target geometry, i.e. the target Entity’s GeoProperty to which the geoquery is to be applied, can be specified by an extra parameter named geoproperty. The GeoProperty’s name shall be specified as short hand name and not a fully qualified one, because, when the query language is used, an @context properly defining all the terms (as per clause 5.5.7) shall be issued. If no geoproperty is specified, the geoquery is applied to the default Property location (see clause 4.7.1).

-

Note that proper URL encoding shall be used by HTTP binding API clients when using these examples.

-
-
-

EXAMPLE 1:

-
-
-

?georel=near;maxDistance==2000

-
&geometry=Point
-&coordinates=[8,40]
-&geoproperty=observationSpace
-
-
-
-
-

EXAMPLE 2:

-
-
-

?georel=within

-
&geometry=Polygon
-&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],
-[100.0,0.0]]]
-&geoproperty=location
-
-
-
-
-

EXAMPLE 3:

-
-
-

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 .

-
&geometry=Point
-&coordinates=[8,40]
-
-
-

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

-
- -
-
- -
-
- -
-

When resolving geo-queries, Entities which do not convey the target GeoProperty of the query shall be considered as non-matching.

-

4.11 NGSI-LD Temporal Query Language

-

The NGSI-LD Temporal Query language shall be supported by implementations. It is intended to define predicates which allow testing whether Temporal Properties of NGSI-LD Entities, Properties and Relationships, are within certain temporal constraints. In particular it can be used to request historic Property values and Relationships that were valid within the specified timeframe.

-

The following grammar defines the syntax that shall be supported:

-
timerel = beforeRel / afterRel / betweenRel
-beforeRel = "before"
-afterRel = "after"
-betweenRel = "between"
-

The points in time for comparison are defined as follows:

-
- -
-

The Temporal Property (see clause 4.8) to which the temporal query is to be applied can be specified by timeproperty. If no timeproperty is specified, the temporal query is applied to the default Temporal Property observedAt.

-
-
-

EXAMPLE 1:

-
-
-

?timerel=before &timeAt=2017-12-13T14:20:00Z

-
-
-
-
-

EXAMPLE 2:

-
-
-

?timerel=between &timeAt=2017-12-13T14:20:00Z &endTimeAt=2017-12-13T14:40:00Z &timeproperty=modifiedAt

-
-
-
-
-

EXAMPLE 3:

-
-
-

Temporal query encoded as HTTP Query String, note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.18.3.2 .

-
&timeproperty=observedAt
-&timeAt=2017-12-13T14:20:00Z
-
-
-

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

-
- -
-

When resolving temporal queries, Entities which do not convey the target Temporal Property of the query shall be considered as non-matching.

-

4.12 NGSI-LD Pagination

-

NGSI-LD operations can potentially return a result set including a large number of NGSI-LD Elements, so that pagination of query results shall be supported by compliant implementations.

-

The list of operations that incur this behaviour is as follows:

-
- -
-

Nonetheless, the NGSI-LD API is agnostic about specific pagination mechanisms and only defines the behaviour that shall be observed by NGSI-LD Systems.

-

For each operation above, NGSI-LD Systems shall:

-
- -
-

NGSI-LD implementations should:

-
- -
-

NGSI-LD implementations may:

-
- -
-

The concrete realization of the features described above might depend on each API binding. Nonetheless, NGSI-LD Systems shall implement pagination features as mandated by the present clause, for any API binding.

-

4.13 Counting the Number of Results

-

Given that NGSI-LD Query operations can potentially return a result set including a large number of NGSI-LD Elements and that pagination of query results shall be supported (see clause 4.12), compliant implementations shall also support a mechanism for relaying to the client the number of expected resulting elements, when a query is executed.

-

A specific field (e.g. a custom header in the response in case of HTTP binding, see clause 6.3.13) shall be returned within the response of a query, whenever this is requested by the client.

-

Mechanisms for limiting the number of returned NGSI-LD Elements are independent of the counting mechanism, so that, potentially, a client can issue a query that limits to zero the number of desired results but asks for the count to be present.

-

This is useful for client-side planning and fine-tuning of subsequent queries and their parameters.

-

4.14 Supporting Multiple Tenants

-

The concept of a Tenant is that a user or group of users utilizes a single instance of an NGSI-LD system (Context Source or Context Broker) in isolation from other users or groups of users of the same instance, which are considered to be different Tenants. Thus a multi-tenant NGSI-LD system is a system where a single software instance is used by different users or groups of users, the Tenants, where 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. Typically, multi-tenancy is used together with an access control mechanism, enforcing the isolation of Tenants, however access control and other security-related aspects are out-of-scope of the present document.

-

The NGSI-LD API optionally enables multi-tenant systems. To support this, Tenant information can be optionally specified in NGSI-LD API operations. The operation then only applies to the targeted Tenant. As all information of one Tenant is isolated from other Tenants, the NGSI-LD API operations for managing, retrieving and subscribing to entity information, but also any context source related operations only apply to the information of the specified Tenant in isolation and never have any effect on the information of other Tenants.

-

As the support and use of Tenants is optional, any operation not explicitly specifying a Tenant targets a default Tenant, which always exists. NGSI-LD systems not supporting multiple Tenants should raise an error of type NoMultiTenantSupport if a Tenant is specified. To enable Context Sources to be part of tenant-based distributed or federated systems, Tenant information can optionally be specified in Context Source Registrations. When contacting the respective Context Sources, the Tenant information from the Context Source Registration has to be used. If no Tenant information is present in the Context Source Registration, no Tenant information is to be used and thus the default Tenant is targeted on the registered Context Source. This enables integrating Context Sources not supporting multi-tenancy in a distributed system with a Tenant-based Context Broker or integrating local Tenants in a federated system using a different Tenant.

-

4.15 NGSI-LD Language Filter

-

The NGSI-LD Language Filter shall be supported by implementations. It is intended to form a mechanism which allows just one matching string value of LanguageProperties of NGSI-LD Entities to be converted to an NGSI-LD Property, where the value will be a string for the specified natural language.

-

The following grammar defines the syntax that shall be supported by the filter:

-
-

lang = langtag

-
-

Where the langtag is defined according to the rules as mandated by IETF RFC 5646 [28], and IETF RFC 3282 [29]. If the Context Broker cannot serve any matching language, it shall default to any supported language. This behaviour can be triggered by specifying lang=“*”in the filter (see example 3).

-

In any case, the attribute in question shall be augmented with an additional non-reified subproperty lang indicating the actual language returned.

-
-
-

EXAMPLE 1:

-
-
-

Specified natural language - return LanguageProperties as strings in English only.

-
-
-
-
-

lang=“en”

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Multiple natural languages with no ranked preference - return LanguageProperties as strings in either Swiss French or French.

-
-
-
-
-

lang=“fr-CH,fr”

-
-
-
-
-
-
-

EXAMPLE 3:

-
-
-

Wildcard - return LanguageProperties as a string in any supported language.

-
-
-
-
-

lang=“*”

-
-
-
-
-
-
-

EXAMPLE 4:

-
-
-

Quality value ranking - return all LanguageProperties as a string in Swiss French or French with no ranked preference, fallback to English as a second choice and finally fallback to any other supported language.

-
-
-
-
-

lang=“fr-CH,fr;q=0.9,en;q=0.8,*;q=0.5”

-
-
-
-
-

4.16 Supporting Multiple Entity Types

-

From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any Entity are supported. An Entity is uniquely identified by its id, so whenever information is provided for an Entity with a given id, it is considered part of the same Entity, regardless of the Entity Type(s) specified. To avoid unexpected behaviour, Entity Types can be implicitly added by all operations that update or append attributes. There is no operation to remove Entity Types from an Entity. The philosophy here is to assume that an Entity always had all Entity Types, but possibly not all Entity Types have previously been known in the system. The only option to remove an Entity Type is to delete the Entity and re-create it with the same id. Alternatively, a batch upsert with ‘replace’ update mode can be used, as described in clause 5.6.8.

-

4.17 NGSI-LD Entity Type Selection Language

-

The NGSI-LD Entity Type Selection Language shall be supported by implementations. It is intended to select only those Entities that have the specified Entity Type(s), possibly among others. Entity Types are specified as a disjunction of elements, where each element can either directly be an Entity Type or a conjunction of multiple Entity Types. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Entity Types can also be seen as a list, and to be compatible with previous versions of the NGSI-LD API, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

-
EntityTypes = OrEntityType *(orOp OrEntityType)         ; OrEntityType|OrEntityType
-OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType)
-OrEntityType = EntityType                               ; EntityType
-andOp = %x3B                                ; ;
-orOp = %x7C / %x2C                                                  ; |  ,
-

EntityType is either a valid name as specified in clause 4.6.2 or a URI.

-
-
-

EXAMPLE 1:

-
-
-

Entities of type Building or House:

-
-
-
-
-

Building|House

-
-
-
-
-
-
-

Building,House

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Entities of type Home and Vehicle:

-
-
-
-
-

(Home;Vehicle)

-
-
-
-
-
-
-

EXAMPLE 3:

-
-
-

Entities of type (Home and Vehicle) or Motorhome:

-
-
-
-
-

(Home;Vehicle)|Motorhome

-
-
-
-
-
-
-

(Home;Vehicle),Motorhome

-
-
-
-
-
-
-

NOTE:

-
-
-

The special characters “,” , “;” , “(” and “)” used in the Entity Type Selection Language are allowed characters in URIs. The use of short names is recommended.

-
-
-

4.18 NGSI-LD Scopes

-

An NGSI-LD Scope enables putting Entities into a hierarchical structure and restrict results of queries and notifications accordingly. The hierarchical structure is user-defined, e.g. according to (logical) location or organization. The use of Scopes is optional and an Entity can be assigned to one or more Scopes at the same time. The Scope is represented as a special scope Property that is non-reified in the normalized Entity representation and reified in the temporal representation of an Entity. In the latter case, it is restricted to having the non-reified Temporal Properties createdAt, modifiedAt and deletedAt as sub-Properties. There shall at most be one instance of the scope property per Entity. In case multiple representations of the same Entity have to be merged, e.g. when combining the results of distributed queries, the values of scope are merged. The value of scope is represented as a JSON array in case there is more than one Scope. For the Temporal Evolution a given Scope is considered valid from the time it has been set until the time it has been explicitly removed by an update or delete operation (for an example see annex C, clause C.5.16).

-

The grammar that encodes the syntax of the Scope is expressed in ABNF format [12]. It is described below (it has been validated using <https://github.com/ietf-tools/bap>), and it shall be supported by implementations. The special string “urn:ngsi-ld:null” (i.e. the NGSI-LD Null) shall be only used and only appear in case of deleted scopes.

-
Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)              ; [/] ScopeLevel *(/ScopeLevel)
-Scope =/ "urn:ngsi-ld:null"                               ; the literal string "urn:ngsi-ld:null"
-ScopeLevel = unicodeLetter *ScopeLevelChar
-ScopeLevelChar = unicodeNumber / unicodeLetter
-ScopeLevelChar =/ %x5F                                    ; _
-
-
-

EXAMPLE 1:

-
-
-

/Madrid

-
-
-
-
-

EXAMPLE 2:

-
-
-

Madrid

-
-
-
-
-

EXAMPLE 3:

-
-
-

/Madrid/Gardens/ParqueNorte

-
-
-
-
-

EXAMPLE 4:

-
-
-

/CompanyA/OrganizationB/UnitC

-
-
-

4.19 NGSI-LD Scope Query Language

-

The NGSI-LD Scope Query Language shall be supported by implementations. It is intended to select only those Entities that are within the specified Scope(s). Scopes are specified as a disjunction of elements, where each element can either directly be a Scope or a conjunction of multiple Scopes. The “+” can be used as a wildcard to match a single scope level within a Scope. The “#” that can be added at the end of a Scope specification serves as a wildcard, which matches the given scope and the whole hierarchy of scopes below. The “/#” matches any non-empty scope, i.e. only explicitly specified scopes. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Scopes can also be seen as a list, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

-
ScopesQ = OrScopeQ *(orOp OrScopeQ)         ; OrScopeQ|OrScopeQ
-ScopesQ =/ %x2F %23             ; / #
-OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29                 ; (ScopeQ;ScopeQ)
-OrScopeQ =/ ScopeQ *1(%x2F %23)                             ; ScopeQ / #
-andOp = %x3B                                ; ;
-orOp = %x7C / %x2C                                                  ; |  ,
-ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel)
-ScopeQLevel = unicodeLetter *ScopeQLevelChar
-ScopeQLevel =/ %x2B             ; + 
-ScopeQLevelChar = unicodeNumber / unicodeLetter
-ScopeQLevelChar =/ %x5F                                             ; _
-
-
-

EXAMPLE 1:

-
-
-

Scope /Madrid:

-
-
-
-
-

/Madrid

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Scope /Madrid/Gardens and the whole scope tree below:

-
/Madrid/Gardens/#,
-/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur
-
-
-
-
-

EXAMPLE 3:

-
-
-

Scopes /Madrid/Gardens/ParqueNorte and /Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first scope level and ParqueNorte as third scope level:

-
-
-
-
-

/Madrid/+/ParqueNorte

-
-
-
-
-
-
-

EXAMPLE 4:

-
-
-

Scope /Madrid/Districts and /CompanyA:

-
-
-
-
-

(/Madrid/Districts;/CompanyA)

-
-
-
-
-
-
-

EXAMPLE 5:

-
-
-

Scope (/Madrid/Districts and /CompanyA) or /CompanyB:

-
-
-
-
-

(/Madrid/Districts;/CompanyA)|CompanyB

-
-
-
-
-
-
-

(/Madrid/Districts;/CompanyA),CompanyB

-
-
-
-
-

4.20 NGSI-LD Distributed Operation names

-

When registering Context Sources (see clause 5.2.9), the registrant NGSI-LD interface endpoint may optionally offer a subset of NGSI-LD operations which it accepts. Table 4.20‑1 defines a list of names for each of these operations.

-
-

Table 4.20-1: Names of implemented Operations

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Operation name -
-Implements -
-
-Context Information Provision -
-createEntity -
-5.6.1 Create Entity -
-updateEntity -
-5.6.2 Update Attributes -
-appendAttrs -
-5.6.3 Append Attributes -
-updateAttrs -
-5.6.4 Partial Attribute update -
-deleteAttrs -
-5.6.5 Delete Attribute -
-deleteEntity -
-5.6.6 Delete Entity -
-createBatch -
-5.6.7 Batch Entity Creation -
-upsertBatch -
-5.6.8 Batch Entity Creation or Update (Upsert) -
-updateBatch -
-5.6.9 Batch Entity Update -
-deleteBatch -
-5.6.10 Batch Entity Delete -
-upsertTemporal -
-5.6.11 Create or Update Temporal Evolution of an Entity -
-appendAttrsTemporal -
-5.6.12 Add Attributes to Temporal Evolution of an Entity -
-deleteAttrsTemporal -
-5.6.13 Delete Attributes from Temporal Evolution of an Entity -
-updateAttrInstanceTemporal -
-5.6.14 Partial Update Attribute Instance in Temporal Evolution of an Entity -
-deleteAttrInstanceTemporal -
-5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity -
-deleteTemporal -
-5.6.16 Delete Temporal Evolution of an Entity -
-mergeEntity -
-5.6.17 Merge Entity -
-replaceEntity -
-5.6.18 Replace Entity -
-replaceAttrs -
-5.6.19 Replace Attribute -
-mergeBatch -
-5.6.20 Batch Entity Merge -
-purgeEntity -
-5.6.21 Purge Entities -
-Context Information Consumption -
-retrieveEntity -
-5.7.1 Retrieve Entity -
-queryEntity -
-5.7.2 Query Entities (excluding batch entity queries) -
-queryBatch -
-5.7.2 Query Entities (batch entity queries only) -
-retrieveTemporal -
-5.7.3 Retrieve Temporal Evolution of an Entity -
-queryTemporal -
-5.7.4 Query Temporal Evolution of Entities -
-retrieveEntityTypes -
-5.7.5 Retrieve Available Entity Types -
-retrieveEntityTypeDetails -
-5.7.6 Retrieve Details of Available Entity Types -
-retrieveEntityTypeInfo -
-5.7.7 Retrieve Available Entity Type Information -
-retrieveAttrTypes -
-5.7.8 Retrieve Available Attributes -
-retrieveAttrTypeDetails -
-5.7.9 Retrieve Details of Available Attributes -
-retrieveAttrTypeInfo -
-5.7.10 Retrieve Available Attribute Information -
-Context Information Subscription -
-createSubscription -
-5.8.1 Create Subscription -
-updateSubscription -
-5.8.2 Update Subscription -
-retrieveSubscription -
-5.8.3 Retrieve Subscription -
-querySubscription -
-5.8.4 Query Subscription -
-deleteSubscription -
-5.8.5 Delete Subscription -
-Support operations for distributed operations -
-retrieveEntityMap -
-5.14.1 Retrieve EntityMap -
-updateEntityMap -
-5.14.2 Update EntityMap -
-deleteEntityMap -
-5.14.3 Delete EntityMap -
-createEntityMapQueryEntity -
-5.14.4 Create EntityMap for Query Entities -
-createEntityMapQueryTemporal -
-5.14.5 Create EntityMap for Query Temporal Evolution of Entities -
-retrieveContextSourceIdentity -
-5.15.1 Retrieve Context Source Identity Information -
-

In addition to these individual operations, a series of names for common groups of operations have also been defined. Table 4.20‑2 defines a list of names for each of these operation groups.

-
-

Table 4.20-2: Named Operation Groups

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Operation Group name -
-Implements -
-federationOps -
-
    -
  • retrieveEntity
    • -
  • queryEntity
    • -
  • queryBatch
    • -
  • retrieveEntityTypes
    • -
  • retrieveEntityTypeDetails
    • -
  • retrieveEntityTypeInfo
    • -
  • retrieveAttrTypes
    • -
  • retrieveAttrTypeDetails
    • -
  • retrieveAttrTypeInfo
    • -
  • createSubscription
    • -
  • updateSubscription
    • -
  • retrieveSubscription
    • -
  • querySubscription
    • -
  • deleteSubscription
    • -
  • retrieveEntityMap
    • -
  • updateEntityMap
    • -
  • deleteEntityMap
    • -
  • createEntityMapQueryEntity
    • -
  • retrieveContextSourceIdentity
    • -
-
-associationOps -
-updateOps -
-
    -
  • updateEntity
    • -
  • updateAttrs
    • -
  • replaceEntity
    • -
  • replaceAttrs
    • -
-
-retrieveOps -
-
    -
  • retrieveEntity
    • -
  • queryEntity
    • -
-
-redirectionOps -
-
    -
  • createEntity
    • -
  • updateEntity
    • -
  • appendAttrs
    • -
  • updateAttrs
    • -
  • deleteAttrs
    • -
  • deleteEntity
    • -
  • mergeEntity
    • -
  • replaceEntity
    • -
  • replaceAttrs
    • -
  • retrieveEntity
    • -
  • queryEntity
    • -
  • purgeEntity
    • -
  • retrieveEntityTypes
    • -
  • retrieveEntityTypeDetails
    • -
  • retrieveEntityTypeInfo
    • -
  • retrieveAttrTypes
    • -
  • retrieveAttrTypeDetails
    • -
  • retrieveAttrTypeInfo
    • -
  • retrieveEntityMap
    • -
  • updateEntityMap
    • -
  • deleteEntityMap
    • -
  • createEntityMapQueryEntity
    • -
  • retrieveContextSourceIdentity
    • -
-
-

If no specific subset of operations is defined for a Context Source Registration, the default set of operations matches the group defined as “federationOps”.

-

4.21 NGSI-LD Attribute Projection Language

-

The NGSI-LD Attribute Projection Language shall be supported by implementations for projection parameters (e.g. pick and omit). Its aim is to specify the Attributes to be retrieved within an Entity (or associated Linked Entities when Linked Entity Retrieval is used). Projected Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or in the case of Linked Entity Retrieval, a Relationship name followed by an Attribute name within the Linked Entity. Since a disjunction of Attributes is a list, either a comma or a pipe character can be used as alternative representations of the or operator. In the following, ABNF grammar for NGSI-LD Attribute Projection Language is given.

-
orOp = %x7C / %x2C                                                  ; |  ,
-ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm)
-LinkedEntityTerm  = %x7B ProjectionTerm %x7D        ; {ProjectionTerm}
-

See clause 4.9 for the definition of AttrName.

-
-
-

EXAMPLE 1:

-
-
-

?pick=temperature

-
-
-
-
-

EXAMPLE 2:

-
-
-

?pick=temperature,humidity

-
-
-
-
-

EXAMPLE 3:

-
-
-

?pick=observation{temperature,humidity}

-
-
-

4.22 Transient Storage of Entities and Attributes

-

In some cases, it is desirable to create an Entity (or Attribute) which is only expected to be stored for a defined period of time. Thereafter such an Entity (or Attribute) should be removed, and can be safely deleted from the context via an automatic garbage collection process.

-

In this regard NGSI-LD defines the following system Property of type TemporalProperty that shall be supported by implementations:

-
- -
-

It should be noted that clean-up processes will only run periodically, and will be dependent upon the Context Broker implementation, therefore final deletion will always lag the expiresAt timestamp to a certain extent. Furthermore, expiresAt only applies to the local storage, i.e. the Entity or Attribute is to be deleted locally, but not on other Context Sources or Context Broker hosting such Entity information, where no expiresAt timestamp is present. Thus expiresAt is not considered to be intrinsic to the Entity or Attribute, but only applies to the storage of the Entity or Attribute respectively. As it pertains to a system function (the deletion from storage after the expiration time), it is considered to be a system attribute.

-

4.23 Entity Ordering

-

4.23.1 Introduction

-

When a Context Consumer queries for Entities retrieved from a single context broker, it shall be possible to request that the array of Entities returned are ordered according to the values held within an Entity Attribute. Context Broker implementations shall interpret such requests and return the array of Entities sorted accordingly.

-

For each Attribute name listed, one of four types of sort order can be specified:

-
- -
-

When sorting by ascending or descending order, the preferred sort order for numbers and datetimes is trivial, however for strings the default collation order shall be defined as using ICU “root” collation order (“und-x-icu”) which returns a reasonable language-agnostic sort order (see IETF RFC 6067 [36]).

-

Sort by distance shall be limited to GeoProperties, and shall be defined as calculating spherical distance using the Haversine formula.

-

Sort ordering is never applied to distributed operations, and the defined sort ordering strategy may depend on implementation specific configurations.

-

4.23.2 Datatype Comparison Order

-

When sorting by value, and the values of Attributes are of mixed datatypes, the following comparison order (null values last), shall be implicitly applied:

-
- -
-

Additionally, when sorting by distance, the following comparison order, shall be applied:

-
- -
-

4.23.3 NGSI-LD Entity Ordering Language

-

The NGSI-LD Entity Ordering Language shall be supported by implementations for the order parameter (i.e. orderBy). Its aim is to specify the Attributes to be used when ordering an Array of Entities retrieved. Ordering Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or an Attribute name followed by a direction (either ascending or descending, where ascending shall be the default if not supplied). The comma character shall be used to separate the elements to be used for ordering which shall be applied sequentially.

-

In the following, ABNF grammar for NGSI-LD Entity Ordering Language is given.

-
thenOp = %x2C                                                       ; ,
-directionOp ::= asc | desc | dist-asc|
-dist-desc
-OrderingTerm = AttrName *1(DirectionTerm) *(thenOp OrderingTerm)
-DirectionTerm = %x3B directionOp.                                   ; ;
-

See clause 4.9 for the definition of AttrName.

-
-
-

EXAMPLE 1:

-
-
-

?orderBy=name - applies sort ordering to rank Entities in ascending order using the value of the name Attribute.

-
-
-
-
-

EXAMPLE 2:

-
-
-

?orderBy=name,age - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by ascending order using the age Attribute.

-
-
-
-
-

EXAMPLE 3:

-
-
-

?orderBy=name,age;desc - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by descending order using the value of age Attribute.

-
-
-
-
-

EXAMPLE 4:

-
-
-

?orderBy=address[city] - applies sort ordering using a sub-item within a Property Value defined as a complex JSON object. The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property .

-
-
-
-
-

EXAMPLE 5:

-
-
-

?orderBy=name.observedAt - applies sort ordering based on 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.

-
-
-

When sorting data using a specific ICU collation order as defined by IETF RFC 6067 [36], the collation element (parameter name collation) shall represent the preferred ordering.

-
-
-

EXAMPLE 6:

-
-
-

?orderBy=name&collation=und-u-ks-identic - applies sort ordering to rank Entities in ascending order using the case insensitive value of the name Attribute.

-
-
-
-
-

EXAMPLE 7:

-
-
-

?orderBy=name&collation=de-u-co-phonebk - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and sorted according to German phonebook collation ordering.

-
-
-

For sort by distance, the coordinates element (parameter name orderFrom) shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [8], section 3.1.2.

-
-
-

EXAMPLE 8:

-
-
-

?orderBy=location;dist-asc&orderFrom=[8,40] - applies sort ordering to rank Entities in ascending distance from a Point with respect to the location GeoProperty .

-
-
-
-
-

EXAMPLE 9:

-
-
-

?orderBy=location;dist-desc&orderFrom=[8,40] - applies sort ordering to rank Entities in descending distance from a Point with respect to the location GeoProperty .

-
-
-
-
-

EXAMPLE 10:

-
-
-

?orderBy=location;dist-asc

-
&orderFrom=[[8,40],[9,42],[9,45],[8,40]]
-&orderGeometry=LineString
-
-
- - diff --git a/API-html/index.html b/API-html/index.html deleted file mode 100644 index 3a0c49a029f6c177ed5e21049860f9b31b6d0e14..0000000000000000000000000000000000000000 --- a/API-html/index.html +++ /dev/null @@ -1,1409 +0,0 @@ - - - - - - - -consolidated - - - - - - - - -
- - diff --git a/API-html/sitemap.json b/API-html/sitemap.json deleted file mode 100644 index e1b5317540fd8a461df2405c634b097037acf3a2..0000000000000000000000000000000000000000 --- a/API-html/sitemap.json +++ /dev/null @@ -1 +0,0 @@ -{"section":{"id":"","level":"0","number":null,"path":"index.html","title":""},"subsections":[{"section":{"id":"intellectual-property-rights","level":"1","number":"1","path":"1-intellectual-property-rights.html#intellectual-property-rights","title":"Intellectual Property Rights"},"subsections":[]},{"section":{"id":"foreword","level":"1","number":"2","path":"2-foreword.html#foreword","title":"Foreword"},"subsections":[]},{"section":{"id":"modal-verbs-terminology","level":"1","number":"3","path":"3-modal-verbs-terminology.html#modal-verbs-terminology","title":"Modal verbs terminology"},"subsections":[]},{"section":{"id":"executive-summary","level":"1","number":"4","path":"4-executive-summary.html#executive-summary","title":"Executive summary"},"subsections":[]},{"section":{"id":"introduction","level":"1","number":"5","path":"5-introduction.html#introduction","title":"Introduction"},"subsections":[]},{"section":{"id":"tabscope","level":"1","number":"6","path":"6-tabscope.html#tabscope","title":"1 Scope"},"subsections":[]},{"section":{"id":"tabreferences","level":"1","number":"7","path":"7-tabreferences.html#tabreferences","title":"2 References"},"subsections":[{"section":{"id":"tabnormative-references","level":"2","number":"7.1","path":"7-tabreferences.html#tabnormative-references","title":"2.1 Normative references"},"subsections":[]},{"section":{"id":"tabinformative-references","level":"2","number":"7.2","path":"7-tabreferences.html#tabinformative-references","title":"2.2 Informative references"},"subsections":[]}]},{"section":{"id":"tabdefinition-of-terms-symbols-and-abbreviations","level":"1","number":"8","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabdefinition-of-terms-symbols-and-abbreviations","title":"3 Definition of terms, symbols and abbreviations"},"subsections":[{"section":{"id":"tabterms","level":"2","number":"8.1","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabterms","title":"3.1 Terms"},"subsections":[]},{"section":{"id":"tabsymbols","level":"2","number":"8.2","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabsymbols","title":"3.2 Symbols"},"subsections":[]},{"section":{"id":"tababbreviations","level":"2","number":"8.3","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tababbreviations","title":"3.3 Abbreviations"},"subsections":[]}]},{"section":{"id":"tabcontext-information-management-framework","level":"1","number":"9","path":"9-tabcontext-information-management-framework.html#tabcontext-information-management-framework","title":"4 Context Information Management Framework"},"subsections":[{"section":{"id":"tabintroduction","level":"2","number":"9.1","path":"9-tabcontext-information-management-framework.html#tabintroduction","title":"4.1 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-information-model","level":"2","number":"9.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-information-model","title":"4.2 NGSI-LD Information Model"},"subsections":[{"section":{"id":"tabintroduction-1","level":"3","number":"9.2.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-1","title":"4.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-meta-model","level":"3","number":"9.2.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-meta-model","title":"4.2.2 NGSI-LD Meta Model"},"subsections":[]},{"section":{"id":"tabcross-domain-ontology","level":"3","number":"9.2.3","path":"9-tabcontext-information-management-framework.html#tabcross-domain-ontology","title":"4.2.3 Cross Domain Ontology"},"subsections":[]},{"section":{"id":"tabngsi-ld-domain-specific-models-and-instantiation","level":"3","number":"9.2.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-domain-specific-models-and-instantiation","title":"4.2.4 NGSI-LD domain-specific models and instantiation"},"subsections":[]},{"section":{"id":"tabuml-representation","level":"3","number":"9.2.5","path":"9-tabcontext-information-management-framework.html#tabuml-representation","title":"4.2.5 UML representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-architectural-considerations","level":"2","number":"9.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-architectural-considerations","title":"4.3 NGSI-LD Architectural Considerations"},"subsections":[{"section":{"id":"tabintroduction-2","level":"3","number":"9.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-2","title":"4.3.1 Introduction"},"subsections":[]},{"section":{"id":"tabcentralized-architecture","level":"3","number":"9.3.2","path":"9-tabcontext-information-management-framework.html#tabcentralized-architecture","title":"4.3.2 Centralized architecture"},"subsections":[]},{"section":{"id":"tabdistributed-architecture","level":"3","number":"9.3.3","path":"9-tabcontext-information-management-framework.html#tabdistributed-architecture","title":"4.3.3 Distributed architecture"},"subsections":[]},{"section":{"id":"tabfederated-architecture","level":"3","number":"9.3.4","path":"9-tabcontext-information-management-framework.html#tabfederated-architecture","title":"4.3.4 Federated architecture"},"subsections":[]},{"section":{"id":"tabngsi-ld-api-structure-and-implementation-options","level":"3","number":"9.3.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-api-structure-and-implementation-options","title":"4.3.5 NGSI-LD API Structure and Implementation Options"},"subsections":[]},{"section":{"id":"tabdistributed-operations","level":"3","number":"9.3.6","path":"9-tabcontext-information-management-framework.html#tabdistributed-operations","title":"4.3.6 Distributed Operations"},"subsections":[{"section":{"id":"tabintroduction-3","level":"4","number":"9.3.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-3","title":"4.3.6.1 Introduction"},"subsections":[]},{"section":{"id":"tabadditive-registrations","level":"4","number":"9.3.6.2","path":"9-tabcontext-information-management-framework.html#tabadditive-registrations","title":"4.3.6.2 Additive Registrations"},"subsections":[]},{"section":{"id":"tabproxied-registrations","level":"4","number":"9.3.6.3","path":"9-tabcontext-information-management-framework.html#tabproxied-registrations","title":"4.3.6.3 Proxied Registrations"},"subsections":[]},{"section":{"id":"tablimiting-cascading-distributed-operations","level":"4","number":"9.3.6.4","path":"9-tabcontext-information-management-framework.html#tablimiting-cascading-distributed-operations","title":"4.3.6.4 Limiting Cascading Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source","level":"4","number":"9.3.6.5","path":"9-tabcontext-information-management-framework.html#tabextra-information-to-provide-when-contacting-context-source","title":"4.3.6.5 Extra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","level":"4","number":"9.3.6.6","path":"9-tabcontext-information-management-framework.html#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","title":"4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source"},"subsections":[]},{"section":{"id":"tabquerying-and-retrieving-distributed-entities-as-unitary-operations","level":"4","number":"9.3.6.7","path":"9-tabcontext-information-management-framework.html#tabquerying-and-retrieving-distributed-entities-as-unitary-operations","title":"4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations"},"subsections":[]},{"section":{"id":"tabbackwards-compatibility-of-context-source-payloads","level":"4","number":"9.3.6.8","path":"9-tabcontext-information-management-framework.html#tabbackwards-compatibility-of-context-source-payloads","title":"4.3.6.8 Backwards compatibility of Context Source payloads"},"subsections":[]}]},{"section":{"id":"tabsnapshots","level":"3","number":"9.3.7","path":"9-tabcontext-information-management-framework.html#tabsnapshots","title":"4.3.7 Snapshots"},"subsections":[]}]},{"section":{"id":"tabcore-and-user-ngsi-ld-context","level":"2","number":"9.4","path":"9-tabcontext-information-management-framework.html#tabcore-and-user-ngsi-ld-context","title":"4.4 Core and user NGSI-LD @context"},"subsections":[]},{"section":{"id":"tabngsi-ld-data-representation","level":"2","number":"9.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-data-representation","title":"4.5 NGSI-LD Data Representation"},"subsections":[{"section":{"id":"tabintroduction-4","level":"3","number":"9.5.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-4","title":"4.5.0 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-representation","level":"3","number":"9.5.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-representation","title":"4.5.1 NGSI-LD Entity Representation"},"subsections":[]},{"section":{"id":"tabngsi-ld-property-representations","level":"3","number":"9.5.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-property-representations","title":"4.5.2 NGSI-LD Property Representations"},"subsections":[{"section":{"id":"tabintroduction-5","level":"4","number":"9.5.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-5","title":"4.5.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-property","level":"4","number":"9.5.3.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-property","title":"4.5.2.2 Normalized NGSI-LD Property"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-property","level":"4","number":"9.5.3.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-property","title":"4.5.2.3 Concise NGSI-LD Property"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-relationship-representations","level":"3","number":"9.5.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-relationship-representations","title":"4.5.3 NGSI-LD Relationship Representations"},"subsections":[{"section":{"id":"tabintroduction-6","level":"4","number":"9.5.4.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-6","title":"4.5.3.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-relationship","level":"4","number":"9.5.4.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-relationship","title":"4.5.3.2 Normalized NGSI-LD Relationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-relationship","level":"4","number":"9.5.4.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-relationship","title":"4.5.3.3 Concise NGSI-LD Relationship"},"subsections":[]}]},{"section":{"id":"tabsimplified-representation","level":"3","number":"9.5.5","path":"9-tabcontext-information-management-framework.html#tabsimplified-representation","title":"4.5.4 Simplified Representation"},"subsections":[]},{"section":{"id":"tabmulti-attribute-support","level":"3","number":"9.5.6","path":"9-tabcontext-information-management-framework.html#tabmulti-attribute-support","title":"4.5.5 Multi-Attribute Support"},"subsections":[{"section":{"id":"tabintroduction-7","level":"4","number":"9.5.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-7","title":"4.5.5.1 Introduction"},"subsections":[]},{"section":{"id":"tabprocessing-of-conflicting-transient-entities","level":"4","number":"9.5.6.2","path":"9-tabcontext-information-management-framework.html#tabprocessing-of-conflicting-transient-entities","title":"4.5.5.2 Processing of Conflicting Transient Entities"},"subsections":[]},{"section":{"id":"tabprocessing-of-conflicting-attributes","level":"4","number":"9.5.6.3","path":"9-tabcontext-information-management-framework.html#tabprocessing-of-conflicting-attributes","title":"4.5.5.3 Processing of Conflicting Attributes"},"subsections":[]}]},{"section":{"id":"tabtemporal-representation-of-an-entity","level":"3","number":"9.5.7","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-an-entity","title":"4.5.6 Temporal Representation of an Entity"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-property","level":"3","number":"9.5.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-property","title":"4.5.7 Temporal Representation of a Property"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-relationship","level":"3","number":"9.5.9","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-relationship","title":"4.5.8 Temporal Representation of a Relationship"},"subsections":[]},{"section":{"id":"tabsimplified-temporal-representation-of-an-entity","level":"3","number":"9.5.10","path":"9-tabcontext-information-management-framework.html#tabsimplified-temporal-representation-of-an-entity","title":"4.5.9 Simplified temporal representation of an Entity"},"subsections":[]},{"section":{"id":"tabentity-type-list-representation","level":"3","number":"9.5.11","path":"9-tabcontext-information-management-framework.html#tabentity-type-list-representation","title":"4.5.10 Entity Type List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-entity-type-list-representation","level":"3","number":"9.5.12","path":"9-tabcontext-information-management-framework.html#tabdetailed-entity-type-list-representation","title":"4.5.11 Detailed Entity Type List Representation"},"subsections":[]},{"section":{"id":"tabentity-type-information-representation","level":"3","number":"9.5.13","path":"9-tabcontext-information-management-framework.html#tabentity-type-information-representation","title":"4.5.12 Entity Type Information Representation"},"subsections":[]},{"section":{"id":"tabattribute-list-representation","level":"3","number":"9.5.14","path":"9-tabcontext-information-management-framework.html#tabattribute-list-representation","title":"4.5.13 Attribute List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-attribute-list-representation","level":"3","number":"9.5.15","path":"9-tabcontext-information-management-framework.html#tabdetailed-attribute-list-representation","title":"4.5.14 Detailed Attribute List Representation"},"subsections":[]},{"section":{"id":"tabattribute-information-representation","level":"3","number":"9.5.16","path":"9-tabcontext-information-management-framework.html#tabattribute-information-representation","title":"4.5.15 Attribute Information Representation"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-entities","level":"3","number":"9.5.17","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-entities","title":"4.5.16 GeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword","level":"4","number":"9.5.17.1","path":"9-tabcontext-information-management-framework.html#tabforeword","title":"4.5.16.0 Foreword"},"subsections":[]},{"section":{"id":"tabtop-level-geometry-field-selection-algorithm","level":"4","number":"9.5.17.2","path":"9-tabcontext-information-management-framework.html#tabtop-level-geometry-field-selection-algorithm","title":"4.5.16.1 Top-level “geometry” field selection algorithm"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-an-individual-entity","level":"4","number":"9.5.17.3","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-an-individual-entity","title":"4.5.16.2 GeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-multiple-entities","level":"4","number":"9.5.17.4","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-multiple-entities","title":"4.5.16.3 GeoJSON Representation of Multiple Entities"},"subsections":[]}]},{"section":{"id":"tabsimplified-geojson-representation-of-entities","level":"3","number":"9.5.18","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-entities","title":"4.5.17 Simplified GeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword-1","level":"4","number":"9.5.18.1","path":"9-tabcontext-information-management-framework.html#tabforeword-1","title":"4.5.17.0 Foreword"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-an-individual-entity","level":"4","number":"9.5.18.2","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-an-individual-entity","title":"4.5.17.1 Simplified GeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-multiple-entities","level":"4","number":"9.5.18.3","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-multiple-entities","title":"4.5.17.2 Simplified GeoJSON Representation of multiple Entities"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-languageproperty-representations","level":"3","number":"9.5.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-languageproperty-representations","title":"4.5.18 NGSI-LD LanguageProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-8","level":"4","number":"9.5.19.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-8","title":"4.5.18.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-languageproperty","level":"4","number":"9.5.19.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-languageproperty","title":"4.5.18.2 Normalized NGSI-LD LanguageProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-languageproperty","level":"4","number":"9.5.19.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-languageproperty","title":"4.5.18.3 Concise NGSI-LD LanguageProperty"},"subsections":[]}]},{"section":{"id":"tabaggregated-temporal-representation-of-an-entity","level":"3","number":"9.5.20","path":"9-tabcontext-information-management-framework.html#tabaggregated-temporal-representation-of-an-entity","title":"4.5.19 Aggregated temporal representation of an Entity"},"subsections":[{"section":{"id":"tabforeword-2","level":"4","number":"9.5.20.1","path":"9-tabcontext-information-management-framework.html#tabforeword-2","title":"4.5.19.0 Foreword"},"subsections":[]},{"section":{"id":"tabsupported-behaviours-for-aggregation-functions","level":"4","number":"9.5.20.2","path":"9-tabcontext-information-management-framework.html#tabsupported-behaviours-for-aggregation-functions","title":"4.5.19.1 Supported behaviours for aggregation functions"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-vocabproperty-representations","level":"3","number":"9.5.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-vocabproperty-representations","title":"4.5.20 NGSI-LD VocabProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-9","level":"4","number":"9.5.21.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-9","title":"4.5.20.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-vocabproperty","title":"4.5.20.2 Normalized NGSI-LD VocabProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-vocabproperty","title":"4.5.20.3 Concise NGSI-LD VocabProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listproperty-representations","level":"3","number":"9.5.22","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listproperty-representations","title":"4.5.21 NGSI-LD ListProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-10","level":"4","number":"9.5.22.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-10","title":"4.5.21.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listproperty","level":"4","number":"9.5.22.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listproperty","title":"4.5.21.2 Normalized NGSI-LD ListProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listproperty","level":"4","number":"9.5.22.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listproperty","title":"4.5.21.3 Concise NGSI-LD ListProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listrelationship-representations","level":"3","number":"9.5.23","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listrelationship-representations","title":"4.5.22 NGSI-LD ListRelationship Representations"},"subsections":[{"section":{"id":"tabintroduction-11","level":"4","number":"9.5.23.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-11","title":"4.5.22.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listrelationship","level":"4","number":"9.5.23.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listrelationship","title":"4.5.22.2 Normalized NGSI-LD ListRelationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listrelationship","level":"4","number":"9.5.23.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listrelationship","title":"4.5.22.3 Concise NGSI-LD ListRelationship"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-linked-entity-retrieval","level":"3","number":"9.5.24","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-linked-entity-retrieval","title":"4.5.23 NGSI-LD Linked Entity Retrieval"},"subsections":[{"section":{"id":"tabintroduction-12","level":"4","number":"9.5.24.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-12","title":"4.5.23.1 Introduction"},"subsections":[]},{"section":{"id":"tabinline-linked-entity-representation","level":"4","number":"9.5.24.2","path":"9-tabcontext-information-management-framework.html#tabinline-linked-entity-representation","title":"4.5.23.2 Inline Linked Entity Representation"},"subsections":[]},{"section":{"id":"tabflattened-linked-entity-representation","level":"4","number":"9.5.24.3","path":"9-tabcontext-information-management-framework.html#tabflattened-linked-entity-representation","title":"4.5.23.3 Flattened Linked Entity Representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-jsonproperty-representations","level":"3","number":"9.5.25","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-jsonproperty-representations","title":"4.5.24 NGSI-LD JsonProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-13","level":"4","number":"9.5.25.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-13","title":"4.5.24.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-jsonproperty","title":"4.5.24.2 Normalized NGSI-LD JsonProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-jsonproperty","title":"4.5.24.3 Concise NGSI-LD JsonProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-entitymap-representation","level":"3","number":"9.5.26","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entitymap-representation","title":"4.5.25 NGSI-LD EntityMap Representation"},"subsections":[]}]},{"section":{"id":"tabdata-representation-restrictions","level":"2","number":"9.6","path":"9-tabcontext-information-management-framework.html#tabdata-representation-restrictions","title":"4.6 Data Representation Restrictions"},"subsections":[{"section":{"id":"tabsupported-text-encodings","level":"3","number":"9.6.1","path":"9-tabcontext-information-management-framework.html#tabsupported-text-encodings","title":"4.6.1 Supported text encodings"},"subsections":[]},{"section":{"id":"tabsupported-names","level":"3","number":"9.6.2","path":"9-tabcontext-information-management-framework.html#tabsupported-names","title":"4.6.2 Supported names"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-values","level":"3","number":"9.6.3","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-values","title":"4.6.3 Supported data types for Values"},"subsections":[]},{"section":{"id":"tabsupported-content","level":"3","number":"9.6.4","path":"9-tabcontext-information-management-framework.html#tabsupported-content","title":"4.6.4 Supported Content"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-languagemaps","level":"3","number":"9.6.5","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-languagemaps","title":"4.6.5 Supported data types for LanguageMaps"},"subsections":[]},{"section":{"id":"tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","level":"3","number":"9.6.6","path":"9-tabcontext-information-management-framework.html#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","title":"4.6.6 Ordering of Entities in arrays having more than one instance of the same Entity"},"subsections":[]}]},{"section":{"id":"tabgeospatial-properties","level":"2","number":"9.7","path":"9-tabcontext-information-management-framework.html#tabgeospatial-properties","title":"4.7 Geospatial Properties"},"subsections":[{"section":{"id":"tabgeojson-geometries","level":"3","number":"9.7.1","path":"9-tabcontext-information-management-framework.html#tabgeojson-geometries","title":"4.7.1 GeoJSON Geometries"},"subsections":[]},{"section":{"id":"tabrepresentation-of-geojson-geometries-in-json-ld","level":"3","number":"9.7.2","path":"9-tabcontext-information-management-framework.html#tabrepresentation-of-geojson-geometries-in-json-ld","title":"4.7.2 Representation of GeoJSON Geometries in JSON-LD"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-geoproperty","level":"3","number":"9.7.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-geoproperty","title":"4.7.3 Concise NGSI-LD GeoProperty"},"subsections":[]}]},{"section":{"id":"tabtemporal-properties","level":"2","number":"9.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-properties","title":"4.8 Temporal Properties"},"subsections":[]},{"section":{"id":"tabngsi-ld-query-language","level":"2","number":"9.9","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-query-language","title":"4.9 NGSI-LD Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-geoquery-language","level":"2","number":"9.10","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-geoquery-language","title":"4.10 NGSI-LD Geoquery Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-temporal-query-language","level":"2","number":"9.11","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-temporal-query-language","title":"4.11 NGSI-LD Temporal Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-pagination","level":"2","number":"9.12","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-pagination","title":"4.12 NGSI-LD Pagination"},"subsections":[]},{"section":{"id":"tabcounting-the-number-of-results","level":"2","number":"9.13","path":"9-tabcontext-information-management-framework.html#tabcounting-the-number-of-results","title":"4.13 Counting the Number of Results"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-tenants","level":"2","number":"9.14","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-tenants","title":"4.14 Supporting Multiple Tenants"},"subsections":[]},{"section":{"id":"tabngsi-ld-language-filter","level":"2","number":"9.15","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-language-filter","title":"4.15 NGSI-LD Language Filter"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-entity-types","level":"2","number":"9.16","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-entity-types","title":"4.16 Supporting Multiple Entity Types"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-type-selection-language","level":"2","number":"9.17","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-type-selection-language","title":"4.17 NGSI-LD Entity Type Selection Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-scopes","level":"2","number":"9.18","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scopes","title":"4.18 NGSI-LD Scopes"},"subsections":[]},{"section":{"id":"tabngsi-ld-scope-query-language","level":"2","number":"9.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scope-query-language","title":"4.19 NGSI-LD Scope Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-distributed-operation-names","level":"2","number":"9.20","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-distributed-operation-names","title":"4.20 NGSI-LD Distributed Operation names"},"subsections":[]},{"section":{"id":"tabngsi-ld-attribute-projection-language","level":"2","number":"9.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-attribute-projection-language","title":"4.21 NGSI-LD Attribute Projection Language"},"subsections":[]},{"section":{"id":"tabtransient-storage-of-entities-and-attributes","level":"2","number":"9.22","path":"9-tabcontext-information-management-framework.html#tabtransient-storage-of-entities-and-attributes","title":"4.22 Transient Storage of Entities and Attributes"},"subsections":[]},{"section":{"id":"tabentity-ordering","level":"2","number":"9.23","path":"9-tabcontext-information-management-framework.html#tabentity-ordering","title":"4.23 Entity Ordering"},"subsections":[{"section":{"id":"tabintroduction-14","level":"3","number":"9.23.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-14","title":"4.23.1 Introduction"},"subsections":[]},{"section":{"id":"tabdatatype-comparison-order","level":"3","number":"9.23.2","path":"9-tabcontext-information-management-framework.html#tabdatatype-comparison-order","title":"4.23.2 Datatype Comparison Order"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-ordering-language","level":"3","number":"9.23.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-ordering-language","title":"4.23.3 NGSI-LD Entity Ordering Language"},"subsections":[]}]}]},{"section":{"id":"tabapi-operation-definition","level":"1","number":"10","path":"10-tabapi-operation-definition.html#tabapi-operation-definition","title":"5 API Operation Definition"},"subsections":[{"section":{"id":"tabintroduction-15","level":"2","number":"10.1","path":"10-tabapi-operation-definition.html#tabintroduction-15","title":"5.1 Introduction"},"subsections":[]},{"section":{"id":"tabdata-types","level":"2","number":"10.2","path":"10-tabapi-operation-definition.html#tabdata-types","title":"5.2 Data Types"},"subsections":[{"section":{"id":"tabintroduction-16","level":"3","number":"10.2.1","path":"10-tabapi-operation-definition.html#tabintroduction-16","title":"5.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabcommon-members","level":"3","number":"10.2.2","path":"10-tabapi-operation-definition.html#tabcommon-members","title":"5.2.2 Common members"},"subsections":[]},{"section":{"id":"tabcontext","level":"3","number":"10.2.3","path":"10-tabapi-operation-definition.html#tabcontext","title":"5.2.3 @context"},"subsections":[]},{"section":{"id":"tabentity","level":"3","number":"10.2.4","path":"10-tabapi-operation-definition.html#tabentity","title":"5.2.4 Entity"},"subsections":[]},{"section":{"id":"tabproperty","level":"3","number":"10.2.5","path":"10-tabapi-operation-definition.html#tabproperty","title":"5.2.5 Property"},"subsections":[]},{"section":{"id":"tabrelationship","level":"3","number":"10.2.6","path":"10-tabapi-operation-definition.html#tabrelationship","title":"5.2.6 Relationship"},"subsections":[]},{"section":{"id":"tabgeoproperty","level":"3","number":"10.2.7","path":"10-tabapi-operation-definition.html#tabgeoproperty","title":"5.2.7 GeoProperty"},"subsections":[]},{"section":{"id":"tabentityinfo","level":"3","number":"10.2.8","path":"10-tabapi-operation-definition.html#tabentityinfo","title":"5.2.8 EntityInfo"},"subsections":[]},{"section":{"id":"tabcsourceregistration","level":"3","number":"10.2.9","path":"10-tabapi-operation-definition.html#tabcsourceregistration","title":"5.2.9 CSourceRegistration"},"subsections":[]},{"section":{"id":"tabregistrationinfo","level":"3","number":"10.2.10","path":"10-tabapi-operation-definition.html#tabregistrationinfo","title":"5.2.10 RegistrationInfo"},"subsections":[]},{"section":{"id":"tabtimeinterval","level":"3","number":"10.2.11","path":"10-tabapi-operation-definition.html#tabtimeinterval","title":"5.2.11 TimeInterval"},"subsections":[]},{"section":{"id":"tabsubscription","level":"3","number":"10.2.12","path":"10-tabapi-operation-definition.html#tabsubscription","title":"5.2.12 Subscription"},"subsections":[]},{"section":{"id":"tabgeoquery","level":"3","number":"10.2.13","path":"10-tabapi-operation-definition.html#tabgeoquery","title":"5.2.13 GeoQuery"},"subsections":[]},{"section":{"id":"tabnotificationparams","level":"3","number":"10.2.14","path":"10-tabapi-operation-definition.html#tabnotificationparams","title":"5.2.14 NotificationParams"},"subsections":[{"section":{"id":"tabnotificationparams-data-type-definition","level":"4","number":"10.2.14.1","path":"10-tabapi-operation-definition.html#tabnotificationparams-data-type-definition","title":"5.2.14.1 NotificationParams data type definition"},"subsections":[]},{"section":{"id":"taboutput-only-members","level":"4","number":"10.2.14.2","path":"10-tabapi-operation-definition.html#taboutput-only-members","title":"5.2.14.2 Output only members"},"subsections":[]}]},{"section":{"id":"tabendpoint","level":"3","number":"10.2.15","path":"10-tabapi-operation-definition.html#tabendpoint","title":"5.2.15 Endpoint"},"subsections":[]},{"section":{"id":"tabbatchoperationresult","level":"3","number":"10.2.16","path":"10-tabapi-operation-definition.html#tabbatchoperationresult","title":"5.2.16 BatchOperationResult"},"subsections":[]},{"section":{"id":"tabbatchentityerror","level":"3","number":"10.2.17","path":"10-tabapi-operation-definition.html#tabbatchentityerror","title":"5.2.17 BatchEntityError"},"subsections":[]},{"section":{"id":"tabupdateresult","level":"3","number":"10.2.18","path":"10-tabapi-operation-definition.html#tabupdateresult","title":"5.2.18 UpdateResult"},"subsections":[]},{"section":{"id":"tabnotupdateddetails","level":"3","number":"10.2.19","path":"10-tabapi-operation-definition.html#tabnotupdateddetails","title":"5.2.19 NotUpdatedDetails"},"subsections":[]},{"section":{"id":"tabentitytemporal","level":"3","number":"10.2.20","path":"10-tabapi-operation-definition.html#tabentitytemporal","title":"5.2.20 EntityTemporal"},"subsections":[]},{"section":{"id":"tabtemporalquery","level":"3","number":"10.2.21","path":"10-tabapi-operation-definition.html#tabtemporalquery","title":"5.2.21 TemporalQuery"},"subsections":[]},{"section":{"id":"tabkeyvaluepair","level":"3","number":"10.2.22","path":"10-tabapi-operation-definition.html#tabkeyvaluepair","title":"5.2.22 KeyValuePair"},"subsections":[]},{"section":{"id":"tabquery","level":"3","number":"10.2.23","path":"10-tabapi-operation-definition.html#tabquery","title":"5.2.23 Query"},"subsections":[]},{"section":{"id":"tabentitytypelist","level":"3","number":"10.2.24","path":"10-tabapi-operation-definition.html#tabentitytypelist","title":"5.2.24 EntityTypeList"},"subsections":[]},{"section":{"id":"tabentitytype","level":"3","number":"10.2.25","path":"10-tabapi-operation-definition.html#tabentitytype","title":"5.2.25 EntityType"},"subsections":[]},{"section":{"id":"tabentitytypeinfo","level":"3","number":"10.2.26","path":"10-tabapi-operation-definition.html#tabentitytypeinfo","title":"5.2.26 EntityTypeInfo"},"subsections":[]},{"section":{"id":"tabattributelist","level":"3","number":"10.2.27","path":"10-tabapi-operation-definition.html#tabattributelist","title":"5.2.27 AttributeList"},"subsections":[]},{"section":{"id":"tabattribute","level":"3","number":"10.2.28","path":"10-tabapi-operation-definition.html#tabattribute","title":"5.2.28 Attribute"},"subsections":[]},{"section":{"id":"tabfeature","level":"3","number":"10.2.29","path":"10-tabapi-operation-definition.html#tabfeature","title":"5.2.29 Feature"},"subsections":[]},{"section":{"id":"tabfeaturecollection","level":"3","number":"10.2.30","path":"10-tabapi-operation-definition.html#tabfeaturecollection","title":"5.2.30 FeatureCollection"},"subsections":[]},{"section":{"id":"tabfeatureproperties","level":"3","number":"10.2.31","path":"10-tabapi-operation-definition.html#tabfeatureproperties","title":"5.2.31 FeatureProperties"},"subsections":[]},{"section":{"id":"tablanguageproperty","level":"3","number":"10.2.32","path":"10-tabapi-operation-definition.html#tablanguageproperty","title":"5.2.32 LanguageProperty"},"subsections":[]},{"section":{"id":"tabentityselector","level":"3","number":"10.2.33","path":"10-tabapi-operation-definition.html#tabentityselector","title":"5.2.33 EntitySelector"},"subsections":[]},{"section":{"id":"tabregistrationmanagementinfo","level":"3","number":"10.2.34","path":"10-tabapi-operation-definition.html#tabregistrationmanagementinfo","title":"5.2.34 RegistrationManagementInfo"},"subsections":[]},{"section":{"id":"tabvocabproperty","level":"3","number":"10.2.35","path":"10-tabapi-operation-definition.html#tabvocabproperty","title":"5.2.35 VocabProperty"},"subsections":[]},{"section":{"id":"tablistproperty","level":"3","number":"10.2.36","path":"10-tabapi-operation-definition.html#tablistproperty","title":"5.2.36 ListProperty"},"subsections":[]},{"section":{"id":"tablistrelationship","level":"3","number":"10.2.37","path":"10-tabapi-operation-definition.html#tablistrelationship","title":"5.2.37 ListRelationship"},"subsections":[]},{"section":{"id":"tabjsonproperty","level":"3","number":"10.2.38","path":"10-tabapi-operation-definition.html#tabjsonproperty","title":"5.2.38 JsonProperty"},"subsections":[]},{"section":{"id":"tabentitymap","level":"3","number":"10.2.39","path":"10-tabapi-operation-definition.html#tabentitymap","title":"5.2.39 EntityMap"},"subsections":[]},{"section":{"id":"tabcontext-source-identity","level":"3","number":"10.2.40","path":"10-tabapi-operation-definition.html#tabcontext-source-identity","title":"5.2.40 Context Source Identity"},"subsections":[]},{"section":{"id":"tabsnapshot","level":"3","number":"10.2.41","path":"10-tabapi-operation-definition.html#tabsnapshot","title":"5.2.41 Snapshot"},"subsections":[]},{"section":{"id":"tabexecutionresultdetails","level":"3","number":"10.2.42","path":"10-tabapi-operation-definition.html#tabexecutionresultdetails","title":"5.2.42 ExecutionResultDetails"},"subsections":[]},{"section":{"id":"taborderingparams","level":"3","number":"10.2.43","path":"10-tabapi-operation-definition.html#taborderingparams","title":"5.2.43 OrderingParams"},"subsections":[]},{"section":{"id":"tabaggregationparams","level":"3","number":"10.2.44","path":"10-tabapi-operation-definition.html#tabaggregationparams","title":"5.2.44 AggregationParams"},"subsections":[]}]},{"section":{"id":"tabnotification-data-types","level":"2","number":"10.3","path":"10-tabapi-operation-definition.html#tabnotification-data-types","title":"5.3 Notification data types"},"subsections":[{"section":{"id":"tabnotification","level":"3","number":"10.3.1","path":"10-tabapi-operation-definition.html#tabnotification","title":"5.3.1 Notification"},"subsections":[]},{"section":{"id":"tabcsourcenotification","level":"3","number":"10.3.2","path":"10-tabapi-operation-definition.html#tabcsourcenotification","title":"5.3.2 CSourceNotification"},"subsections":[]},{"section":{"id":"tabtriggerreasonenumeration","level":"3","number":"10.3.3","path":"10-tabapi-operation-definition.html#tabtriggerreasonenumeration","title":"5.3.3 TriggerReasonEnumeration"},"subsections":[]},{"section":{"id":"tabsnapshotnotification","level":"3","number":"10.3.4","path":"10-tabapi-operation-definition.html#tabsnapshotnotification","title":"5.3.4 SnapshotNotification"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-fragments","level":"2","number":"10.4","path":"10-tabapi-operation-definition.html#tabngsi-ld-fragments","title":"5.4 NGSI-LD Fragments"},"subsections":[]},{"section":{"id":"tabcommon-behaviours","level":"2","number":"10.5","path":"10-tabapi-operation-definition.html#tabcommon-behaviours","title":"5.5 Common Behaviours"},"subsections":[{"section":{"id":"tabintroduction-17","level":"3","number":"10.5.1","path":"10-tabapi-operation-definition.html#tabintroduction-17","title":"5.5.1 Introduction"},"subsections":[]},{"section":{"id":"taberror-types","level":"3","number":"10.5.2","path":"10-tabapi-operation-definition.html#taberror-types","title":"5.5.2 Error types"},"subsections":[]},{"section":{"id":"taberror-response-payload-body","level":"3","number":"10.5.3","path":"10-tabapi-operation-definition.html#taberror-response-payload-body","title":"5.5.3 Error response payload body"},"subsections":[]},{"section":{"id":"tabgeneral-ngsi-ld-validation","level":"3","number":"10.5.4","path":"10-tabapi-operation-definition.html#tabgeneral-ngsi-ld-validation","title":"5.5.4 General NGSI-LD validation"},"subsections":[]},{"section":{"id":"tabdefault-context-assignment","level":"3","number":"10.5.5","path":"10-tabapi-operation-definition.html#tabdefault-context-assignment","title":"5.5.5 Default @context assignment"},"subsections":[]},{"section":{"id":"taboperation-execution-and-generic-error-handling","level":"3","number":"10.5.6","path":"10-tabapi-operation-definition.html#taboperation-execution-and-generic-error-handling","title":"5.5.6 Operation execution and generic error handling"},"subsections":[]},{"section":{"id":"tabterm-to-uri-expansion-or-compaction","level":"3","number":"10.5.7","path":"10-tabapi-operation-definition.html#tabterm-to-uri-expansion-or-compaction","title":"5.5.7 Term to URI expansion or compaction"},"subsections":[]},{"section":{"id":"tabpartial-update-patch-behaviour","level":"3","number":"10.5.8","path":"10-tabapi-operation-definition.html#tabpartial-update-patch-behaviour","title":"5.5.8 Partial Update Patch Behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour","level":"3","number":"10.5.9","path":"10-tabapi-operation-definition.html#tabpagination-behaviour","title":"5.5.9 Pagination Behaviour"},"subsections":[{"section":{"id":"tabgeneral-pagination-behaviour","level":"4","number":"10.5.9.1","path":"10-tabapi-operation-definition.html#tabgeneral-pagination-behaviour","title":"5.5.9.1 General Pagination Behaviour"},"subsections":[]},{"section":{"id":"tabpagination-option-using-limit-and-offset","level":"4","number":"10.5.9.2","path":"10-tabapi-operation-definition.html#tabpagination-option-using-limit-and-offset","title":"5.5.9.2 Pagination option using limit and offset"},"subsections":[]},{"section":{"id":"tabpagination-with-entity-maps","level":"4","number":"10.5.9.3","path":"10-tabapi-operation-definition.html#tabpagination-with-entity-maps","title":"5.5.9.3 Pagination with Entity maps"},"subsections":[]}]},{"section":{"id":"tabmulti-tenant-behaviour","level":"3","number":"10.5.10","path":"10-tabapi-operation-definition.html#tabmulti-tenant-behaviour","title":"5.5.10 Multi-Tenant Behaviour"},"subsections":[]},{"section":{"id":"tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","level":"3","number":"10.5.11","path":"10-tabapi-operation-definition.html#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","title":"5.5.11 More than one instance of the same Entity in an Entity array"},"subsections":[{"section":{"id":"tabforeword-3","level":"4","number":"10.5.11.1","path":"10-tabapi-operation-definition.html#tabforeword-3","title":"5.5.11.0 Foreword"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-case","level":"4","number":"10.5.11.2","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-case","title":"5.5.11.1 Batch Entity Creation case"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert-case","level":"4","number":"10.5.11.3","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert-case","title":"5.5.11.2 Batch Entity Creation or Update (Upsert) case"},"subsections":[]},{"section":{"id":"tabbatch-entity-update-case","level":"4","number":"10.5.11.4","path":"10-tabapi-operation-definition.html#tabbatch-entity-update-case","title":"5.5.11.3 Batch Entity Update case"},"subsections":[]},{"section":{"id":"tabbatch-entity-delete-case","level":"4","number":"10.5.11.5","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete-case","title":"5.5.11.4 Batch Entity Delete case"},"subsections":[]},{"section":{"id":"tabbatch-entity-merge-case","level":"4","number":"10.5.11.6","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge-case","title":"5.5.11.5 Batch Entity Merge case"},"subsections":[]}]},{"section":{"id":"tabmerge-patch-behaviour","level":"3","number":"10.5.12","path":"10-tabapi-operation-definition.html#tabmerge-patch-behaviour","title":"5.5.12 Merge Patch Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-operations-to-local-scope","level":"3","number":"10.5.13","path":"10-tabapi-operation-definition.html#tablimiting-operations-to-local-scope","title":"5.5.13 Limiting operations to local scope"},"subsections":[]},{"section":{"id":"tabdistributed-transactional-behaviour","level":"3","number":"10.5.14","path":"10-tabapi-operation-definition.html#tabdistributed-transactional-behaviour","title":"5.5.14 Distributed Transactional Behaviour"},"subsections":[]},{"section":{"id":"tabsnapshot-behaviour","level":"3","number":"10.5.15","path":"10-tabapi-operation-definition.html#tabsnapshot-behaviour","title":"5.5.15 Snapshot Behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-information-provision","level":"2","number":"10.6","path":"10-tabapi-operation-definition.html#tabcontext-information-provision","title":"5.6 Context Information Provision"},"subsections":[{"section":{"id":"tabcreate-entity","level":"3","number":"10.6.1","path":"10-tabapi-operation-definition.html#tabcreate-entity","title":"5.6.1 Create Entity"},"subsections":[{"section":{"id":"tabdescription","level":"4","number":"10.6.1.1","path":"10-tabapi-operation-definition.html#tabdescription","title":"5.6.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram","level":"4","number":"10.6.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram","title":"5.6.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data","level":"4","number":"10.6.1.3","path":"10-tabapi-operation-definition.html#tabinput-data","title":"5.6.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour","level":"4","number":"10.6.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour","title":"5.6.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data","level":"4","number":"10.6.1.5","path":"10-tabapi-operation-definition.html#taboutput-data","title":"5.6.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-attributes","level":"3","number":"10.6.2","path":"10-tabapi-operation-definition.html#tabupdate-attributes","title":"5.6.2 Update Attributes"},"subsections":[{"section":{"id":"tabdescription-1","level":"4","number":"10.6.2.1","path":"10-tabapi-operation-definition.html#tabdescription-1","title":"5.6.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-1","level":"4","number":"10.6.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-1","title":"5.6.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-1","level":"4","number":"10.6.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-1","title":"5.6.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-1","level":"4","number":"10.6.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-1","title":"5.6.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-1","level":"4","number":"10.6.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-1","title":"5.6.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabappend-attributes","level":"3","number":"10.6.3","path":"10-tabapi-operation-definition.html#tabappend-attributes","title":"5.6.3 Append Attributes"},"subsections":[{"section":{"id":"tabdescription-2","level":"4","number":"10.6.3.1","path":"10-tabapi-operation-definition.html#tabdescription-2","title":"5.6.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-2","level":"4","number":"10.6.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-2","title":"5.6.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-2","level":"4","number":"10.6.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-2","title":"5.6.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-2","level":"4","number":"10.6.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-2","title":"5.6.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-2","level":"4","number":"10.6.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-2","title":"5.6.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabpartial-attribute-update","level":"3","number":"10.6.4","path":"10-tabapi-operation-definition.html#tabpartial-attribute-update","title":"5.6.4 Partial Attribute update"},"subsections":[{"section":{"id":"tabdescription-3","level":"4","number":"10.6.4.1","path":"10-tabapi-operation-definition.html#tabdescription-3","title":"5.6.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-3","level":"4","number":"10.6.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-3","title":"5.6.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-3","level":"4","number":"10.6.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-3","title":"5.6.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-3","level":"4","number":"10.6.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-3","title":"5.6.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-3","level":"4","number":"10.6.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-3","title":"5.6.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute","level":"3","number":"10.6.5","path":"10-tabapi-operation-definition.html#tabdelete-attribute","title":"5.6.5 Delete Attribute"},"subsections":[{"section":{"id":"tabdescription-4","level":"4","number":"10.6.5.1","path":"10-tabapi-operation-definition.html#tabdescription-4","title":"5.6.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-4","level":"4","number":"10.6.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-4","title":"5.6.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-4","level":"4","number":"10.6.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-4","title":"5.6.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-4","level":"4","number":"10.6.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-4","title":"5.6.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-4","level":"4","number":"10.6.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-4","title":"5.6.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-entity","level":"3","number":"10.6.6","path":"10-tabapi-operation-definition.html#tabdelete-entity","title":"5.6.6 Delete Entity"},"subsections":[{"section":{"id":"tabdescription-5","level":"4","number":"10.6.6.1","path":"10-tabapi-operation-definition.html#tabdescription-5","title":"5.6.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-5","level":"4","number":"10.6.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-5","title":"5.6.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-5","level":"4","number":"10.6.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-5","title":"5.6.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-5","level":"4","number":"10.6.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-5","title":"5.6.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-5","level":"4","number":"10.6.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-5","title":"5.6.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation","level":"3","number":"10.6.7","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation","title":"5.6.7 Batch Entity Creation"},"subsections":[{"section":{"id":"tabdescription-6","level":"4","number":"10.6.7.1","path":"10-tabapi-operation-definition.html#tabdescription-6","title":"5.6.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-6","level":"4","number":"10.6.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-6","title":"5.6.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-6","level":"4","number":"10.6.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-6","title":"5.6.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-6","level":"4","number":"10.6.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-6","title":"5.6.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-6","level":"4","number":"10.6.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-6","title":"5.6.7.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert","level":"3","number":"10.6.8","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert","title":"5.6.8 Batch Entity Creation or Update (Upsert)"},"subsections":[{"section":{"id":"tabdescription-7","level":"4","number":"10.6.8.1","path":"10-tabapi-operation-definition.html#tabdescription-7","title":"5.6.8.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-7","level":"4","number":"10.6.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-7","title":"5.6.8.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-7","level":"4","number":"10.6.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-7","title":"5.6.8.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-7","level":"4","number":"10.6.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-7","title":"5.6.8.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-7","level":"4","number":"10.6.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-7","title":"5.6.8.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-update","level":"3","number":"10.6.9","path":"10-tabapi-operation-definition.html#tabbatch-entity-update","title":"5.6.9 Batch Entity Update"},"subsections":[{"section":{"id":"tabdescription-8","level":"4","number":"10.6.9.1","path":"10-tabapi-operation-definition.html#tabdescription-8","title":"5.6.9.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-8","level":"4","number":"10.6.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-8","title":"5.6.9.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-8","level":"4","number":"10.6.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-8","title":"5.6.9.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-8","level":"4","number":"10.6.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-8","title":"5.6.9.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-8","level":"4","number":"10.6.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-8","title":"5.6.9.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-delete","level":"3","number":"10.6.10","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete","title":"5.6.10 Batch Entity Delete"},"subsections":[{"section":{"id":"tabdescription-9","level":"4","number":"10.6.10.1","path":"10-tabapi-operation-definition.html#tabdescription-9","title":"5.6.10.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-9","level":"4","number":"10.6.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-9","title":"5.6.10.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-9","level":"4","number":"10.6.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-9","title":"5.6.10.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-9","level":"4","number":"10.6.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-9","title":"5.6.10.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-9","level":"4","number":"10.6.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-9","title":"5.6.10.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-or-update-upsert-temporal-evolution-of-an-entity","level":"3","number":"10.6.11","path":"10-tabapi-operation-definition.html#tabcreate-or-update-upsert-temporal-evolution-of-an-entity","title":"5.6.11 Create or Update (Upsert) Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-10","level":"4","number":"10.6.11.1","path":"10-tabapi-operation-definition.html#tabdescription-10","title":"5.6.11.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-10","level":"4","number":"10.6.11.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-10","title":"5.6.11.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-10","level":"4","number":"10.6.11.3","path":"10-tabapi-operation-definition.html#tabinput-data-10","title":"5.6.11.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-10","level":"4","number":"10.6.11.4","path":"10-tabapi-operation-definition.html#tabbehaviour-10","title":"5.6.11.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-10","level":"4","number":"10.6.11.5","path":"10-tabapi-operation-definition.html#taboutput-data-10","title":"5.6.11.5 Output data"},"subsections":[]}]},{"section":{"id":"tabadd-attributes-to-temporal-evolution-of-an-entity","level":"3","number":"10.6.12","path":"10-tabapi-operation-definition.html#tabadd-attributes-to-temporal-evolution-of-an-entity","title":"5.6.12 Add Attributes to Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-11","level":"4","number":"10.6.12.1","path":"10-tabapi-operation-definition.html#tabdescription-11","title":"5.6.12.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-11","level":"4","number":"10.6.12.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-11","title":"5.6.12.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-11","level":"4","number":"10.6.12.3","path":"10-tabapi-operation-definition.html#tabinput-data-11","title":"5.6.12.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-11","level":"4","number":"10.6.12.4","path":"10-tabapi-operation-definition.html#tabbehaviour-11","title":"5.6.12.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-11","level":"4","number":"10.6.12.5","path":"10-tabapi-operation-definition.html#taboutput-data-11","title":"5.6.12.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.13","path":"10-tabapi-operation-definition.html#tabdelete-attribute-from-temporal-evolution-of-an-entity","title":"5.6.13 Delete Attribute from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-12","level":"4","number":"10.6.13.1","path":"10-tabapi-operation-definition.html#tabdescription-12","title":"5.6.13.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-12","level":"4","number":"10.6.13.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-12","title":"5.6.13.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-12","level":"4","number":"10.6.13.3","path":"10-tabapi-operation-definition.html#tabinput-data-12","title":"5.6.13.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-12","level":"4","number":"10.6.13.4","path":"10-tabapi-operation-definition.html#tabbehaviour-12","title":"5.6.13.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-12","level":"4","number":"10.6.13.5","path":"10-tabapi-operation-definition.html#taboutput-data-12","title":"5.6.13.5 Output data"},"subsections":[]}]},{"section":{"id":"tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","level":"3","number":"10.6.14","path":"10-tabapi-operation-definition.html#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","title":"5.6.14 Modify Attribute instance in Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-13","level":"4","number":"10.6.14.1","path":"10-tabapi-operation-definition.html#tabdescription-13","title":"5.6.14.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-13","level":"4","number":"10.6.14.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-13","title":"5.6.14.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-13","level":"4","number":"10.6.14.3","path":"10-tabapi-operation-definition.html#tabinput-data-13","title":"5.6.14.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-13","level":"4","number":"10.6.14.4","path":"10-tabapi-operation-definition.html#tabbehaviour-13","title":"5.6.14.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-13","level":"4","number":"10.6.14.5","path":"10-tabapi-operation-definition.html#taboutput-data-13","title":"5.6.14.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.15","path":"10-tabapi-operation-definition.html#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","title":"5.6.15 Delete Attribute instance from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-14","level":"4","number":"10.6.15.1","path":"10-tabapi-operation-definition.html#tabdescription-14","title":"5.6.15.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-14","level":"4","number":"10.6.15.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-14","title":"5.6.15.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-14","level":"4","number":"10.6.15.3","path":"10-tabapi-operation-definition.html#tabinput-data-14","title":"5.6.15.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-14","level":"4","number":"10.6.15.4","path":"10-tabapi-operation-definition.html#tabbehaviour-14","title":"5.6.15.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-14","level":"4","number":"10.6.15.5","path":"10-tabapi-operation-definition.html#taboutput-data-14","title":"5.6.15.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-temporal-evolution-of-an-entity","level":"3","number":"10.6.16","path":"10-tabapi-operation-definition.html#tabdelete-temporal-evolution-of-an-entity","title":"5.6.16 Delete Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-15","level":"4","number":"10.6.16.1","path":"10-tabapi-operation-definition.html#tabdescription-15","title":"5.6.16.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-15","level":"4","number":"10.6.16.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-15","title":"5.6.16.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-15","level":"4","number":"10.6.16.3","path":"10-tabapi-operation-definition.html#tabinput-data-15","title":"5.6.16.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-15","level":"4","number":"10.6.16.4","path":"10-tabapi-operation-definition.html#tabbehaviour-15","title":"5.6.16.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-15","level":"4","number":"10.6.16.5","path":"10-tabapi-operation-definition.html#taboutput-data-15","title":"5.6.16.5 Output data"},"subsections":[]}]},{"section":{"id":"tabmerge-entity","level":"3","number":"10.6.17","path":"10-tabapi-operation-definition.html#tabmerge-entity","title":"5.6.17 Merge Entity"},"subsections":[{"section":{"id":"tabdescription-16","level":"4","number":"10.6.17.1","path":"10-tabapi-operation-definition.html#tabdescription-16","title":"5.6.17.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-16","level":"4","number":"10.6.17.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-16","title":"5.6.17.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-16","level":"4","number":"10.6.17.3","path":"10-tabapi-operation-definition.html#tabinput-data-16","title":"5.6.17.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-16","level":"4","number":"10.6.17.4","path":"10-tabapi-operation-definition.html#tabbehaviour-16","title":"5.6.17.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-16","level":"4","number":"10.6.17.5","path":"10-tabapi-operation-definition.html#taboutput-data-16","title":"5.6.17.5 Output data"},"subsections":[]}]},{"section":{"id":"tabreplace-entity","level":"3","number":"10.6.18","path":"10-tabapi-operation-definition.html#tabreplace-entity","title":"5.6.18 Replace Entity"},"subsections":[{"section":{"id":"tabdescription-17","level":"4","number":"10.6.18.1","path":"10-tabapi-operation-definition.html#tabdescription-17","title":"5.6.18.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-17","level":"4","number":"10.6.18.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-17","title":"5.6.18.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-17","level":"4","number":"10.6.18.3","path":"10-tabapi-operation-definition.html#tabinput-data-17","title":"5.6.18.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-17","level":"4","number":"10.6.18.4","path":"10-tabapi-operation-definition.html#tabbehaviour-17","title":"5.6.18.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-17","level":"4","number":"10.6.18.5","path":"10-tabapi-operation-definition.html#taboutput-data-17","title":"5.6.18.5 Output data"},"subsections":[]}]},{"section":{"id":"tabreplace-attribute","level":"3","number":"10.6.19","path":"10-tabapi-operation-definition.html#tabreplace-attribute","title":"5.6.19 Replace Attribute"},"subsections":[{"section":{"id":"tabdescription-18","level":"4","number":"10.6.19.1","path":"10-tabapi-operation-definition.html#tabdescription-18","title":"5.6.19.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-18","level":"4","number":"10.6.19.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-18","title":"5.6.19.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-18","level":"4","number":"10.6.19.3","path":"10-tabapi-operation-definition.html#tabinput-data-18","title":"5.6.19.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-18","level":"4","number":"10.6.19.4","path":"10-tabapi-operation-definition.html#tabbehaviour-18","title":"5.6.19.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-18","level":"4","number":"10.6.19.5","path":"10-tabapi-operation-definition.html#taboutput-data-18","title":"5.6.19.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-merge","level":"3","number":"10.6.20","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge","title":"5.6.20 Batch Entity Merge"},"subsections":[{"section":{"id":"tabdescription-19","level":"4","number":"10.6.20.1","path":"10-tabapi-operation-definition.html#tabdescription-19","title":"5.6.20.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-19","level":"4","number":"10.6.20.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-19","title":"5.6.20.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-19","level":"4","number":"10.6.20.3","path":"10-tabapi-operation-definition.html#tabinput-data-19","title":"5.6.20.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-19","level":"4","number":"10.6.20.4","path":"10-tabapi-operation-definition.html#tabbehaviour-19","title":"5.6.20.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-19","level":"4","number":"10.6.20.5","path":"10-tabapi-operation-definition.html#taboutput-data-19","title":"5.6.20.5 Output data"},"subsections":[]}]},{"section":{"id":"tabpurge-entities","level":"3","number":"10.6.21","path":"10-tabapi-operation-definition.html#tabpurge-entities","title":"5.6.21 Purge Entities"},"subsections":[{"section":{"id":"tabdescription-20","level":"4","number":"10.6.21.1","path":"10-tabapi-operation-definition.html#tabdescription-20","title":"5.6.21.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-20","level":"4","number":"10.6.21.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-20","title":"5.6.21.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-20","level":"4","number":"10.6.21.3","path":"10-tabapi-operation-definition.html#tabinput-data-20","title":"5.6.21.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-20","level":"4","number":"10.6.21.4","path":"10-tabapi-operation-definition.html#tabbehaviour-20","title":"5.6.21.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-20","level":"4","number":"10.6.21.5","path":"10-tabapi-operation-definition.html#taboutput-data-20","title":"5.6.21.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-information-consumption","level":"2","number":"10.7","path":"10-tabapi-operation-definition.html#tabcontext-information-consumption","title":"5.7 Context Information Consumption"},"subsections":[{"section":{"id":"tabretrieve-entity","level":"3","number":"10.7.1","path":"10-tabapi-operation-definition.html#tabretrieve-entity","title":"5.7.1 Retrieve Entity"},"subsections":[{"section":{"id":"tabdescription-21","level":"4","number":"10.7.1.1","path":"10-tabapi-operation-definition.html#tabdescription-21","title":"5.7.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-21","level":"4","number":"10.7.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-21","title":"5.7.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-21","level":"4","number":"10.7.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-21","title":"5.7.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-21","level":"4","number":"10.7.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-21","title":"5.7.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-21","level":"4","number":"10.7.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-21","title":"5.7.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-entities","level":"3","number":"10.7.2","path":"10-tabapi-operation-definition.html#tabquery-entities","title":"5.7.2 Query Entities"},"subsections":[{"section":{"id":"tabdescription-22","level":"4","number":"10.7.2.1","path":"10-tabapi-operation-definition.html#tabdescription-22","title":"5.7.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-22","level":"4","number":"10.7.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-22","title":"5.7.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-22","level":"4","number":"10.7.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-22","title":"5.7.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-22","level":"4","number":"10.7.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-22","title":"5.7.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-22","level":"4","number":"10.7.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-22","title":"5.7.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-temporal-evolution-of-an-entity","level":"3","number":"10.7.3","path":"10-tabapi-operation-definition.html#tabretrieve-temporal-evolution-of-an-entity","title":"5.7.3 Retrieve Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-23","level":"4","number":"10.7.3.1","path":"10-tabapi-operation-definition.html#tabdescription-23","title":"5.7.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-23","level":"4","number":"10.7.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-23","title":"5.7.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-23","level":"4","number":"10.7.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-23","title":"5.7.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-23","level":"4","number":"10.7.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-23","title":"5.7.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-23","level":"4","number":"10.7.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-23","title":"5.7.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-temporal-evolution-of-entities","level":"3","number":"10.7.4","path":"10-tabapi-operation-definition.html#tabquery-temporal-evolution-of-entities","title":"5.7.4 Query Temporal Evolution of Entities"},"subsections":[{"section":{"id":"tabdescription-24","level":"4","number":"10.7.4.1","path":"10-tabapi-operation-definition.html#tabdescription-24","title":"5.7.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-24","level":"4","number":"10.7.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-24","title":"5.7.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-24","level":"4","number":"10.7.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-24","title":"5.7.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-24","level":"4","number":"10.7.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-24","title":"5.7.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-24","level":"4","number":"10.7.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-24","title":"5.7.4.5 Output Data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-types","level":"3","number":"10.7.5","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-types","title":"5.7.5 Retrieve Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-25","level":"4","number":"10.7.5.1","path":"10-tabapi-operation-definition.html#tabdescription-25","title":"5.7.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-25","level":"4","number":"10.7.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-25","title":"5.7.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-25","level":"4","number":"10.7.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-25","title":"5.7.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-25","level":"4","number":"10.7.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-25","title":"5.7.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-25","level":"4","number":"10.7.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-25","title":"5.7.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-entity-types","level":"3","number":"10.7.6","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-entity-types","title":"5.7.6 Retrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-26","level":"4","number":"10.7.6.1","path":"10-tabapi-operation-definition.html#tabdescription-26","title":"5.7.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-26","level":"4","number":"10.7.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-26","title":"5.7.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-26","level":"4","number":"10.7.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-26","title":"5.7.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-26","level":"4","number":"10.7.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-26","title":"5.7.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-26","level":"4","number":"10.7.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-26","title":"5.7.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-type-information","level":"3","number":"10.7.7","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-type-information","title":"5.7.7 Retrieve Available Entity Type Information"},"subsections":[{"section":{"id":"tabdescription-27","level":"4","number":"10.7.7.1","path":"10-tabapi-operation-definition.html#tabdescription-27","title":"5.7.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-27","level":"4","number":"10.7.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-27","title":"5.7.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-27","level":"4","number":"10.7.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-27","title":"5.7.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-27","level":"4","number":"10.7.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-27","title":"5.7.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-27","level":"4","number":"10.7.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-27","title":"5.7.7.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attributes","level":"3","number":"10.7.8","path":"10-tabapi-operation-definition.html#tabretrieve-available-attributes","title":"5.7.8 Retrieve Available Attributes"},"subsections":[{"section":{"id":"tabdescription-28","level":"4","number":"10.7.8.1","path":"10-tabapi-operation-definition.html#tabdescription-28","title":"5.7.8.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-28","level":"4","number":"10.7.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-28","title":"5.7.8.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-28","level":"4","number":"10.7.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-28","title":"5.7.8.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-28","level":"4","number":"10.7.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-28","title":"5.7.8.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-28","level":"4","number":"10.7.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-28","title":"5.7.8.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-attributes","level":"3","number":"10.7.9","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-attributes","title":"5.7.9 Retrieve Details of Available Attributes"},"subsections":[{"section":{"id":"tabdescription-29","level":"4","number":"10.7.9.1","path":"10-tabapi-operation-definition.html#tabdescription-29","title":"5.7.9.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-29","level":"4","number":"10.7.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-29","title":"5.7.9.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-29","level":"4","number":"10.7.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-29","title":"5.7.9.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-29","level":"4","number":"10.7.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-29","title":"5.7.9.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-29","level":"4","number":"10.7.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-29","title":"5.7.9.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attribute-information","level":"3","number":"10.7.10","path":"10-tabapi-operation-definition.html#tabretrieve-available-attribute-information","title":"5.7.10 Retrieve Available Attribute Information"},"subsections":[{"section":{"id":"tabdescription-30","level":"4","number":"10.7.10.1","path":"10-tabapi-operation-definition.html#tabdescription-30","title":"5.7.10.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-30","level":"4","number":"10.7.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-30","title":"5.7.10.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-30","level":"4","number":"10.7.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-30","title":"5.7.10.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-30","level":"4","number":"10.7.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-30","title":"5.7.10.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-30","level":"4","number":"10.7.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-30","title":"5.7.10.5 Output data"},"subsections":[]}]},{"section":{"id":"tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","level":"3","number":"10.7.11","path":"10-tabapi-operation-definition.html#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","title":"5.7.11 Architecture-related aspects of retrieval of Entity Types and Attributes"},"subsections":[]}]},{"section":{"id":"tabcontext-information-subscription","level":"2","number":"10.8","path":"10-tabapi-operation-definition.html#tabcontext-information-subscription","title":"5.8 Context Information Subscription"},"subsections":[{"section":{"id":"tabcreate-subscription","level":"3","number":"10.8.1","path":"10-tabapi-operation-definition.html#tabcreate-subscription","title":"5.8.1 Create Subscription"},"subsections":[{"section":{"id":"tabdescription-31","level":"4","number":"10.8.1.1","path":"10-tabapi-operation-definition.html#tabdescription-31","title":"5.8.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-31","level":"4","number":"10.8.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-31","title":"5.8.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-31","level":"4","number":"10.8.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-31","title":"5.8.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-31","level":"4","number":"10.8.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-31","title":"5.8.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-31","level":"4","number":"10.8.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-31","title":"5.8.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-subscription","level":"3","number":"10.8.2","path":"10-tabapi-operation-definition.html#tabupdate-subscription","title":"5.8.2 Update Subscription"},"subsections":[{"section":{"id":"tabdescription-32","level":"4","number":"10.8.2.1","path":"10-tabapi-operation-definition.html#tabdescription-32","title":"5.8.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-32","level":"4","number":"10.8.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-32","title":"5.8.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-32","level":"4","number":"10.8.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-32","title":"5.8.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-32","level":"4","number":"10.8.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-32","title":"5.8.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-32","level":"4","number":"10.8.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-32","title":"5.8.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-subscription","level":"3","number":"10.8.3","path":"10-tabapi-operation-definition.html#tabretrieve-subscription","title":"5.8.3 Retrieve Subscription"},"subsections":[{"section":{"id":"tabdescription-33","level":"4","number":"10.8.3.1","path":"10-tabapi-operation-definition.html#tabdescription-33","title":"5.8.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-33","level":"4","number":"10.8.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-33","title":"5.8.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-33","level":"4","number":"10.8.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-33","title":"5.8.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-33","level":"4","number":"10.8.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-33","title":"5.8.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-33","level":"4","number":"10.8.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-33","title":"5.8.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-subscriptions","level":"3","number":"10.8.4","path":"10-tabapi-operation-definition.html#tabquery-subscriptions","title":"5.8.4 Query Subscriptions"},"subsections":[{"section":{"id":"tabdescription-34","level":"4","number":"10.8.4.1","path":"10-tabapi-operation-definition.html#tabdescription-34","title":"5.8.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-34","level":"4","number":"10.8.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-34","title":"5.8.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-34","level":"4","number":"10.8.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-34","title":"5.8.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-34","level":"4","number":"10.8.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-34","title":"5.8.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-34","level":"4","number":"10.8.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-34","title":"5.8.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-subscription","level":"3","number":"10.8.5","path":"10-tabapi-operation-definition.html#tabdelete-subscription","title":"5.8.5 Delete Subscription"},"subsections":[{"section":{"id":"tabdescription-35","level":"4","number":"10.8.5.1","path":"10-tabapi-operation-definition.html#tabdescription-35","title":"5.8.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-35","level":"4","number":"10.8.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-35","title":"5.8.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-35","level":"4","number":"10.8.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-35","title":"5.8.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-35","level":"4","number":"10.8.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-35","title":"5.8.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-35","level":"4","number":"10.8.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-35","title":"5.8.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour","level":"3","number":"10.8.6","path":"10-tabapi-operation-definition.html#tabnotification-behaviour","title":"5.8.6 Notification behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-source-registration","level":"2","number":"10.9","path":"10-tabapi-operation-definition.html#tabcontext-source-registration","title":"5.9 Context Source Registration"},"subsections":[{"section":{"id":"tabintroduction-18","level":"3","number":"10.9.1","path":"10-tabapi-operation-definition.html#tabintroduction-18","title":"5.9.1 Introduction"},"subsections":[]},{"section":{"id":"tabregister-context-source","level":"3","number":"10.9.2","path":"10-tabapi-operation-definition.html#tabregister-context-source","title":"5.9.2 Register Context Source"},"subsections":[{"section":{"id":"tabdescription-36","level":"4","number":"10.9.2.1","path":"10-tabapi-operation-definition.html#tabdescription-36","title":"5.9.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-36","level":"4","number":"10.9.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-36","title":"5.9.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-36","level":"4","number":"10.9.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-36","title":"5.9.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-36","level":"4","number":"10.9.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-36","title":"5.9.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-36","level":"4","number":"10.9.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-36","title":"5.9.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration","level":"3","number":"10.9.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration","title":"5.9.3 Update Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-37","level":"4","number":"10.9.3.1","path":"10-tabapi-operation-definition.html#tabdescription-37","title":"5.9.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-37","level":"4","number":"10.9.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-37","title":"5.9.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-37","level":"4","number":"10.9.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-37","title":"5.9.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-37","level":"4","number":"10.9.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-37","title":"5.9.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-37","level":"4","number":"10.9.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-37","title":"5.9.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration","level":"3","number":"10.9.4","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration","title":"5.9.4 Delete Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-38","level":"4","number":"10.9.4.1","path":"10-tabapi-operation-definition.html#tabdescription-38","title":"5.9.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-38","level":"4","number":"10.9.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-38","title":"5.9.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-38","level":"4","number":"10.9.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-38","title":"5.9.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-38","level":"4","number":"10.9.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-38","title":"5.9.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-38","level":"4","number":"10.9.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-38","title":"5.9.4.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-discovery","level":"2","number":"10.10","path":"10-tabapi-operation-definition.html#tabcontext-source-discovery","title":"5.10 Context Source Discovery"},"subsections":[{"section":{"id":"tabretrieve-context-source-registration","level":"3","number":"10.10.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration","title":"5.10.1 Retrieve Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-39","level":"4","number":"10.10.1.1","path":"10-tabapi-operation-definition.html#tabdescription-39","title":"5.10.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-39","level":"4","number":"10.10.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-39","title":"5.10.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-39","level":"4","number":"10.10.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-39","title":"5.10.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-39","level":"4","number":"10.10.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-39","title":"5.10.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-39","level":"4","number":"10.10.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-39","title":"5.10.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registrations","level":"3","number":"10.10.2","path":"10-tabapi-operation-definition.html#tabquery-context-source-registrations","title":"5.10.2 Query Context Source Registrations"},"subsections":[{"section":{"id":"tabdescription-40","level":"4","number":"10.10.2.1","path":"10-tabapi-operation-definition.html#tabdescription-40","title":"5.10.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-40","level":"4","number":"10.10.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-40","title":"5.10.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-40","level":"4","number":"10.10.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-40","title":"5.10.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-40","level":"4","number":"10.10.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-40","title":"5.10.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-40","level":"4","number":"10.10.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-40","title":"5.10.2.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-registration-subscription","level":"2","number":"10.11","path":"10-tabapi-operation-definition.html#tabcontext-source-registration-subscription","title":"5.11 Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabintroduction-19","level":"3","number":"10.11.1","path":"10-tabapi-operation-definition.html#tabintroduction-19","title":"5.11.1 Introduction"},"subsections":[]},{"section":{"id":"tabcreate-context-source-registration-subscription","level":"3","number":"10.11.2","path":"10-tabapi-operation-definition.html#tabcreate-context-source-registration-subscription","title":"5.11.2 Create Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-41","level":"4","number":"10.11.2.1","path":"10-tabapi-operation-definition.html#tabdescription-41","title":"5.11.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-41","level":"4","number":"10.11.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-41","title":"5.11.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-41","level":"4","number":"10.11.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-41","title":"5.11.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-41","level":"4","number":"10.11.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-41","title":"5.11.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-41","level":"4","number":"10.11.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-41","title":"5.11.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration-subscription","level":"3","number":"10.11.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration-subscription","title":"5.11.3 Update Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-42","level":"4","number":"10.11.3.1","path":"10-tabapi-operation-definition.html#tabdescription-42","title":"5.11.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-42","level":"4","number":"10.11.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-42","title":"5.11.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-42","level":"4","number":"10.11.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-42","title":"5.11.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-42","level":"4","number":"10.11.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-42","title":"5.11.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-42","level":"4","number":"10.11.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-42","title":"5.11.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-context-source-registration-subscription","level":"3","number":"10.11.4","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration-subscription","title":"5.11.4 Retrieve Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-43","level":"4","number":"10.11.4.1","path":"10-tabapi-operation-definition.html#tabdescription-43","title":"5.11.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-43","level":"4","number":"10.11.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-43","title":"5.11.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-43","level":"4","number":"10.11.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-43","title":"5.11.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-43","level":"4","number":"10.11.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-43","title":"5.11.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-43","level":"4","number":"10.11.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-43","title":"5.11.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registration-subscriptions","level":"3","number":"10.11.5","path":"10-tabapi-operation-definition.html#tabquery-context-source-registration-subscriptions","title":"5.11.5 Query Context Source Registration Subscriptions"},"subsections":[{"section":{"id":"tabdescription-44","level":"4","number":"10.11.5.1","path":"10-tabapi-operation-definition.html#tabdescription-44","title":"5.11.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-44","level":"4","number":"10.11.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-44","title":"5.11.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-44","level":"4","number":"10.11.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-44","title":"5.11.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-44","level":"4","number":"10.11.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-44","title":"5.11.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-44","level":"4","number":"10.11.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-44","title":"5.11.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration-subscription","level":"3","number":"10.11.6","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration-subscription","title":"5.11.6 Delete Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-45","level":"4","number":"10.11.6.1","path":"10-tabapi-operation-definition.html#tabdescription-45","title":"5.11.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-45","level":"4","number":"10.11.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-45","title":"5.11.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-45","level":"4","number":"10.11.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-45","title":"5.11.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-45","level":"4","number":"10.11.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-45","title":"5.11.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-45","level":"4","number":"10.11.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-45","title":"5.11.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour-1","level":"3","number":"10.11.7","path":"10-tabapi-operation-definition.html#tabnotification-behaviour-1","title":"5.11.7 Notification behaviour"},"subsections":[]}]},{"section":{"id":"tabmatching-context-source-registrations","level":"2","number":"10.12","path":"10-tabapi-operation-definition.html#tabmatching-context-source-registrations","title":"5.12 Matching Context Source Registrations"},"subsections":[]},{"section":{"id":"tabstoring-managing-and-serving-contexts","level":"2","number":"10.13","path":"10-tabapi-operation-definition.html#tabstoring-managing-and-serving-contexts","title":"5.13 Storing, Managing and Serving @contexts"},"subsections":[{"section":{"id":"tabintroduction-20","level":"3","number":"10.13.1","path":"10-tabapi-operation-definition.html#tabintroduction-20","title":"5.13.1 Introduction"},"subsections":[]},{"section":{"id":"tabadd-context","level":"3","number":"10.13.2","path":"10-tabapi-operation-definition.html#tabadd-context","title":"5.13.2 Add @context"},"subsections":[{"section":{"id":"tabdescription-46","level":"4","number":"10.13.2.1","path":"10-tabapi-operation-definition.html#tabdescription-46","title":"5.13.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-46","level":"4","number":"10.13.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-46","title":"5.13.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-46","level":"4","number":"10.13.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-46","title":"5.13.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-46","level":"4","number":"10.13.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-46","title":"5.13.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-46","level":"4","number":"10.13.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-46","title":"5.13.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tablist-contexts","level":"3","number":"10.13.3","path":"10-tabapi-operation-definition.html#tablist-contexts","title":"5.13.3 List @contexts"},"subsections":[{"section":{"id":"tabdescription-47","level":"4","number":"10.13.3.1","path":"10-tabapi-operation-definition.html#tabdescription-47","title":"5.13.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-47","level":"4","number":"10.13.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-47","title":"5.13.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-47","level":"4","number":"10.13.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-47","title":"5.13.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-47","level":"4","number":"10.13.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-47","title":"5.13.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-47","level":"4","number":"10.13.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-47","title":"5.13.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabserve-context","level":"3","number":"10.13.4","path":"10-tabapi-operation-definition.html#tabserve-context","title":"5.13.4 Serve @context"},"subsections":[{"section":{"id":"tabdescription-48","level":"4","number":"10.13.4.1","path":"10-tabapi-operation-definition.html#tabdescription-48","title":"5.13.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-48","level":"4","number":"10.13.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-48","title":"5.13.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-48","level":"4","number":"10.13.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-48","title":"5.13.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-48","level":"4","number":"10.13.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-48","title":"5.13.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-48","level":"4","number":"10.13.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-48","title":"5.13.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-and-reload-context","level":"3","number":"10.13.5","path":"10-tabapi-operation-definition.html#tabdelete-and-reload-context","title":"5.13.5 Delete and Reload @context"},"subsections":[{"section":{"id":"tabdescription-49","level":"4","number":"10.13.5.1","path":"10-tabapi-operation-definition.html#tabdescription-49","title":"5.13.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-49","level":"4","number":"10.13.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-49","title":"5.13.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-49","level":"4","number":"10.13.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-49","title":"5.13.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-49","level":"4","number":"10.13.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-49","title":"5.13.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-49","level":"4","number":"10.13.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-49","title":"5.13.5.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-entity-mapping","level":"2","number":"10.14","path":"10-tabapi-operation-definition.html#tabcontext-source-entity-mapping","title":"5.14 Context Source Entity Mapping"},"subsections":[{"section":{"id":"tabretrieve-entitymap","level":"3","number":"10.14.1","path":"10-tabapi-operation-definition.html#tabretrieve-entitymap","title":"5.14.1 Retrieve EntityMap"},"subsections":[{"section":{"id":"tabdescription-50","level":"4","number":"10.14.1.1","path":"10-tabapi-operation-definition.html#tabdescription-50","title":"5.14.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-50","level":"4","number":"10.14.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-50","title":"5.14.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-50","level":"4","number":"10.14.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-50","title":"5.14.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-50","level":"4","number":"10.14.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-50","title":"5.14.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-50","level":"4","number":"10.14.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-50","title":"5.14.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-entitymap","level":"3","number":"10.14.2","path":"10-tabapi-operation-definition.html#tabupdate-entitymap","title":"5.14.2 Update EntityMap"},"subsections":[{"section":{"id":"tabdescription-51","level":"4","number":"10.14.2.1","path":"10-tabapi-operation-definition.html#tabdescription-51","title":"5.14.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-51","level":"4","number":"10.14.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-51","title":"5.14.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-51","level":"4","number":"10.14.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-51","title":"5.14.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-51","level":"4","number":"10.14.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-51","title":"5.14.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-51","level":"4","number":"10.14.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-51","title":"5.14.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-entitymap","level":"3","number":"10.14.3","path":"10-tabapi-operation-definition.html#tabdelete-entitymap","title":"5.14.3 Delete EntityMap"},"subsections":[{"section":{"id":"tabdescription-52","level":"4","number":"10.14.3.1","path":"10-tabapi-operation-definition.html#tabdescription-52","title":"5.14.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-52","level":"4","number":"10.14.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-52","title":"5.14.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-52","level":"4","number":"10.14.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-52","title":"5.14.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-52","level":"4","number":"10.14.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-52","title":"5.14.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-52","level":"4","number":"10.14.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-52","title":"5.14.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-entitymap-for-query-entities","level":"3","number":"10.14.4","path":"10-tabapi-operation-definition.html#tabcreate-entitymap-for-query-entities","title":"5.14.4 Create EntityMap for Query Entities"},"subsections":[{"section":{"id":"tabdescription-53","level":"4","number":"10.14.4.1","path":"10-tabapi-operation-definition.html#tabdescription-53","title":"5.14.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-53","level":"4","number":"10.14.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-53","title":"5.14.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-53","level":"4","number":"10.14.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-53","title":"5.14.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-53","level":"4","number":"10.14.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-53","title":"5.14.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-53","level":"4","number":"10.14.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-53","title":"5.14.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-entitymap-for-query-temporal-evolution-of-entities","level":"3","number":"10.14.5","path":"10-tabapi-operation-definition.html#tabcreate-entitymap-for-query-temporal-evolution-of-entities","title":"5.14.5 Create EntityMap for Query Temporal Evolution of Entities"},"subsections":[{"section":{"id":"tabdescription-54","level":"4","number":"10.14.5.1","path":"10-tabapi-operation-definition.html#tabdescription-54","title":"5.14.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-54","level":"4","number":"10.14.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-54","title":"5.14.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-54","level":"4","number":"10.14.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-54","title":"5.14.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-54","level":"4","number":"10.14.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-54","title":"5.14.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-54","level":"4","number":"10.14.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-54","title":"5.14.5.5 Output Data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-identity-information","level":"2","number":"10.15","path":"10-tabapi-operation-definition.html#tabcontext-source-identity-information","title":"5.15 Context Source Identity Information"},"subsections":[{"section":{"id":"tabretrieve-context-source-identity-information","level":"3","number":"10.15.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-identity-information","title":"5.15.1 Retrieve Context Source Identity Information"},"subsections":[{"section":{"id":"tabdescription-55","level":"4","number":"10.15.1.1","path":"10-tabapi-operation-definition.html#tabdescription-55","title":"5.15.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-55","level":"4","number":"10.15.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-55","title":"5.15.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-55","level":"4","number":"10.15.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-55","title":"5.15.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-55","level":"4","number":"10.15.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-55","title":"5.15.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-55","level":"4","number":"10.15.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-55","title":"5.15.1.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabsnapshot-functionality","level":"2","number":"10.16","path":"10-tabapi-operation-definition.html#tabsnapshot-functionality","title":"5.16 Snapshot Functionality"},"subsections":[{"section":{"id":"tabcreate-snapshot","level":"3","number":"10.16.1","path":"10-tabapi-operation-definition.html#tabcreate-snapshot","title":"5.16.1 Create Snapshot"},"subsections":[{"section":{"id":"tabdescription-56","level":"4","number":"10.16.1.1","path":"10-tabapi-operation-definition.html#tabdescription-56","title":"5.16.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-56","level":"4","number":"10.16.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-56","title":"5.16.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-56","level":"4","number":"10.16.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-56","title":"5.16.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-56","level":"4","number":"10.16.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-56","title":"5.16.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-56","level":"4","number":"10.16.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-56","title":"5.16.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabclone-snapshot","level":"3","number":"10.16.2","path":"10-tabapi-operation-definition.html#tabclone-snapshot","title":"5.16.2 Clone Snapshot"},"subsections":[{"section":{"id":"tabdescription-57","level":"4","number":"10.16.2.1","path":"10-tabapi-operation-definition.html#tabdescription-57","title":"5.16.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-57","level":"4","number":"10.16.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-57","title":"5.16.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-57","level":"4","number":"10.16.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-57","title":"5.16.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-57","level":"4","number":"10.16.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-57","title":"5.16.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-57","level":"4","number":"10.16.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-57","title":"5.16.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-snapshot-status","level":"3","number":"10.16.3","path":"10-tabapi-operation-definition.html#tabretrieve-snapshot-status","title":"5.16.3 Retrieve Snapshot Status"},"subsections":[{"section":{"id":"tabdescription-58","level":"4","number":"10.16.3.1","path":"10-tabapi-operation-definition.html#tabdescription-58","title":"5.16.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-58","level":"4","number":"10.16.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-58","title":"5.16.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-58","level":"4","number":"10.16.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-58","title":"5.16.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-58","level":"4","number":"10.16.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-58","title":"5.16.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-58","level":"4","number":"10.16.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-58","title":"5.16.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-snapshot-status","level":"3","number":"10.16.4","path":"10-tabapi-operation-definition.html#tabupdate-snapshot-status","title":"5.16.4 Update Snapshot Status"},"subsections":[{"section":{"id":"tabdescription-59","level":"4","number":"10.16.4.1","path":"10-tabapi-operation-definition.html#tabdescription-59","title":"5.16.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-59","level":"4","number":"10.16.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-59","title":"5.16.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-59","level":"4","number":"10.16.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-59","title":"5.16.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-59","level":"4","number":"10.16.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-59","title":"5.16.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-59","level":"4","number":"10.16.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-59","title":"5.16.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-snapshot","level":"3","number":"10.16.5","path":"10-tabapi-operation-definition.html#tabdelete-snapshot","title":"5.16.5 Delete Snapshot"},"subsections":[{"section":{"id":"tabdescription-60","level":"4","number":"10.16.5.1","path":"10-tabapi-operation-definition.html#tabdescription-60","title":"5.16.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-60","level":"4","number":"10.16.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-60","title":"5.16.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-60","level":"4","number":"10.16.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-60","title":"5.16.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-60","level":"4","number":"10.16.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-60","title":"5.16.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-60","level":"4","number":"10.16.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-60","title":"5.16.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabsnapshot-status-notification-behaviour","level":"3","number":"10.16.6","path":"10-tabapi-operation-definition.html#tabsnapshot-status-notification-behaviour","title":"5.16.6 Snapshot status notification behaviour"},"subsections":[]},{"section":{"id":"tabpurge-snapshots","level":"3","number":"10.16.7","path":"10-tabapi-operation-definition.html#tabpurge-snapshots","title":"5.16.7 Purge Snapshots"},"subsections":[{"section":{"id":"tabdescription-61","level":"4","number":"10.16.7.1","path":"10-tabapi-operation-definition.html#tabdescription-61","title":"5.16.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-61","level":"4","number":"10.16.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-61","title":"5.16.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-61","level":"4","number":"10.16.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-61","title":"5.16.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-61","level":"4","number":"10.16.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-61","title":"5.16.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-61","level":"4","number":"10.16.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-61","title":"5.16.7.5 Output data"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-http-binding","level":"1","number":"11","path":"11-tabapi-http-binding.html#tabapi-http-binding","title":"6 API HTTP Binding"},"subsections":[{"section":{"id":"tabintroduction-21","level":"2","number":"11.1","path":"11-tabapi-http-binding.html#tabintroduction-21","title":"6.1 Introduction"},"subsections":[]},{"section":{"id":"tabglobal-definitions-and-resource-structure","level":"2","number":"11.2","path":"11-tabapi-http-binding.html#tabglobal-definitions-and-resource-structure","title":"6.2 Global Definitions and Resource Structure"},"subsections":[]},{"section":{"id":"tabcommon-behaviours-1","level":"2","number":"11.3","path":"11-tabapi-http-binding.html#tabcommon-behaviours-1","title":"6.3 Common Behaviours"},"subsections":[{"section":{"id":"tabintroduction-22","level":"3","number":"11.3.1","path":"11-tabapi-http-binding.html#tabintroduction-22","title":"6.3.1 Introduction"},"subsections":[]},{"section":{"id":"taberror-types-1","level":"3","number":"11.3.2","path":"11-tabapi-http-binding.html#taberror-types-1","title":"6.3.2 Error Types"},"subsections":[]},{"section":{"id":"tabreporting-errors","level":"3","number":"11.3.3","path":"11-tabapi-http-binding.html#tabreporting-errors","title":"6.3.3 Reporting errors"},"subsections":[]},{"section":{"id":"tabhttp-request-preconditions","level":"3","number":"11.3.4","path":"11-tabapi-http-binding.html#tabhttp-request-preconditions","title":"6.3.4 HTTP request preconditions"},"subsections":[]},{"section":{"id":"tabjson-ld-context-resolution","level":"3","number":"11.3.5","path":"11-tabapi-http-binding.html#tabjson-ld-context-resolution","title":"6.3.5 JSON-LD @context resolution"},"subsections":[]},{"section":{"id":"tabhttp-response-common-requirements","level":"3","number":"11.3.6","path":"11-tabapi-http-binding.html#tabhttp-response-common-requirements","title":"6.3.6 HTTP response common requirements"},"subsections":[]},{"section":{"id":"tabrepresentation-of-entities","level":"3","number":"11.3.7","path":"11-tabapi-http-binding.html#tabrepresentation-of-entities","title":"6.3.7 Representation of Entities"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-2","level":"3","number":"11.3.8","path":"11-tabapi-http-binding.html#tabnotification-behaviour-2","title":"6.3.8 Notification behaviour"},"subsections":[]},{"section":{"id":"tabcsource-notification-behaviour","level":"3","number":"11.3.9","path":"11-tabapi-http-binding.html#tabcsource-notification-behaviour","title":"6.3.9 Csource Notification behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour-1","level":"3","number":"11.3.10","path":"11-tabapi-http-binding.html#tabpagination-behaviour-1","title":"6.3.10 Pagination behaviour"},"subsections":[]},{"section":{"id":"tabincluding-system-attributes","level":"3","number":"11.3.11","path":"11-tabapi-http-binding.html#tabincluding-system-attributes","title":"6.3.11 Including system Attributes"},"subsections":[]},{"section":{"id":"tabsimplified-or-aggregated-temporal-representation-of-entities","level":"3","number":"11.3.12","path":"11-tabapi-http-binding.html#tabsimplified-or-aggregated-temporal-representation-of-entities","title":"6.3.12 Simplified or aggregated temporal representation of Entities"},"subsections":[]},{"section":{"id":"tabcounting-number-of-results","level":"3","number":"11.3.13","path":"11-tabapi-http-binding.html#tabcounting-number-of-results","title":"6.3.13 Counting number of results"},"subsections":[]},{"section":{"id":"tabtenant-specification","level":"3","number":"11.3.14","path":"11-tabapi-http-binding.html#tabtenant-specification","title":"6.3.14 Tenant specification"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-spatially-bound-entities","level":"3","number":"11.3.15","path":"11-tabapi-http-binding.html#tabgeojson-representation-of-spatially-bound-entities","title":"6.3.15 GeoJSON representation of spatially bound entities"},"subsections":[]},{"section":{"id":"tabexpiration-time-for-cached-contexts","level":"3","number":"11.3.16","path":"11-tabapi-http-binding.html#tabexpiration-time-for-cached-contexts","title":"6.3.16 Expiration time for cached @contexts"},"subsections":[]},{"section":{"id":"tabdistributed-operations-caching-and-timeout-behaviour","level":"3","number":"11.3.17","path":"11-tabapi-http-binding.html#tabdistributed-operations-caching-and-timeout-behaviour","title":"6.3.17 Distributed Operations Caching and Timeout Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-distributed-operations","level":"3","number":"11.3.18","path":"11-tabapi-http-binding.html#tablimiting-distributed-operations","title":"6.3.18 Limiting Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source-1","level":"3","number":"11.3.19","path":"11-tabapi-http-binding.html#tabextra-information-to-provide-when-contacting-context-source-1","title":"6.3.19 Extra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabinvalid-parameters","level":"3","number":"11.3.20","path":"11-tabapi-http-binding.html#tabinvalid-parameters","title":"6.3.20 Invalid parameters"},"subsections":[]},{"section":{"id":"taboptional-profile-information-regarding-versioning-and-datatype-conformance","level":"3","number":"11.3.21","path":"11-tabapi-http-binding.html#taboptional-profile-information-regarding-versioning-and-datatype-conformance","title":"6.3.21 Optional profile information regarding versioning and datatype conformance"},"subsections":[]},{"section":{"id":"tabsnapshot-specification","level":"3","number":"11.3.22","path":"11-tabapi-http-binding.html#tabsnapshot-specification","title":"6.3.22 Snapshot specification"},"subsections":[]}]},{"section":{"id":"tabresource-entities","level":"2","number":"11.4","path":"11-tabapi-http-binding.html#tabresource-entities","title":"6.4 Resource: entities/"},"subsections":[{"section":{"id":"tabdescription-62","level":"3","number":"11.4.1","path":"11-tabapi-http-binding.html#tabdescription-62","title":"6.4.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition","level":"3","number":"11.4.2","path":"11-tabapi-http-binding.html#tabresource-definition","title":"6.4.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods","level":"3","number":"11.4.3","path":"11-tabapi-http-binding.html#tabresource-methods","title":"6.4.3 Resource methods"},"subsections":[{"section":{"id":"tabpost","level":"4","number":"11.4.3.1","path":"11-tabapi-http-binding.html#tabpost","title":"6.4.3.1 POST"},"subsections":[]},{"section":{"id":"tabget","level":"4","number":"11.4.3.2","path":"11-tabapi-http-binding.html#tabget","title":"6.4.3.2 GET"},"subsections":[]},{"section":{"id":"tabdelete","level":"4","number":"11.4.3.3","path":"11-tabapi-http-binding.html#tabdelete","title":"6.4.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityid","level":"2","number":"11.5","path":"11-tabapi-http-binding.html#tabresource-entitiesentityid","title":"6.5 Resource: entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-63","level":"3","number":"11.5.1","path":"11-tabapi-http-binding.html#tabdescription-63","title":"6.5.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-1","level":"3","number":"11.5.2","path":"11-tabapi-http-binding.html#tabresource-definition-1","title":"6.5.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-1","level":"3","number":"11.5.3","path":"11-tabapi-http-binding.html#tabresource-methods-1","title":"6.5.3 Resource methods"},"subsections":[{"section":{"id":"tabget-1","level":"4","number":"11.5.3.1","path":"11-tabapi-http-binding.html#tabget-1","title":"6.5.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-1","level":"4","number":"11.5.3.2","path":"11-tabapi-http-binding.html#tabdelete-1","title":"6.5.3.2 DELETE"},"subsections":[]},{"section":{"id":"tabput","level":"4","number":"11.5.3.3","path":"11-tabapi-http-binding.html#tabput","title":"6.5.3.3 PUT"},"subsections":[]},{"section":{"id":"tabpatch","level":"4","number":"11.5.3.4","path":"11-tabapi-http-binding.html#tabpatch","title":"6.5.3.4 PATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrs","level":"2","number":"11.6","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrs","title":"6.6 Resource: entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-64","level":"3","number":"11.6.1","path":"11-tabapi-http-binding.html#tabdescription-64","title":"6.6.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-2","level":"3","number":"11.6.2","path":"11-tabapi-http-binding.html#tabresource-definition-2","title":"6.6.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-2","level":"3","number":"11.6.3","path":"11-tabapi-http-binding.html#tabresource-methods-2","title":"6.6.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-1","level":"4","number":"11.6.3.1","path":"11-tabapi-http-binding.html#tabpost-1","title":"6.6.3.1 POST"},"subsections":[]},{"section":{"id":"tabpatch-1","level":"4","number":"11.6.3.2","path":"11-tabapi-http-binding.html#tabpatch-1","title":"6.6.3.2 PATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrsattrid","level":"2","number":"11.7","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrsattrid","title":"6.7 Resource: entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-65","level":"3","number":"11.7.1","path":"11-tabapi-http-binding.html#tabdescription-65","title":"6.7.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-3","level":"3","number":"11.7.2","path":"11-tabapi-http-binding.html#tabresource-definition-3","title":"6.7.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-3","level":"3","number":"11.7.3","path":"11-tabapi-http-binding.html#tabresource-methods-3","title":"6.7.3 Resource methods"},"subsections":[{"section":{"id":"tabpatch-2","level":"4","number":"11.7.3.1","path":"11-tabapi-http-binding.html#tabpatch-2","title":"6.7.3.1 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-2","level":"4","number":"11.7.3.2","path":"11-tabapi-http-binding.html#tabdelete-2","title":"6.7.3.2 DELETE"},"subsections":[]},{"section":{"id":"tabput-1","level":"4","number":"11.7.3.3","path":"11-tabapi-http-binding.html#tabput-1","title":"6.7.3.3 PUT"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrations","level":"2","number":"11.8","path":"11-tabapi-http-binding.html#tabresource-csourceregistrations","title":"6.8 Resource: csourceRegistrations/"},"subsections":[{"section":{"id":"tabdescription-66","level":"3","number":"11.8.1","path":"11-tabapi-http-binding.html#tabdescription-66","title":"6.8.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-4","level":"3","number":"11.8.2","path":"11-tabapi-http-binding.html#tabresource-definition-4","title":"6.8.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-4","level":"3","number":"11.8.3","path":"11-tabapi-http-binding.html#tabresource-methods-4","title":"6.8.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-2","level":"4","number":"11.8.3.1","path":"11-tabapi-http-binding.html#tabpost-2","title":"6.8.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-2","level":"4","number":"11.8.3.2","path":"11-tabapi-http-binding.html#tabget-2","title":"6.8.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrationsregistrationid","level":"2","number":"11.9","path":"11-tabapi-http-binding.html#tabresource-csourceregistrationsregistrationid","title":"6.9 Resource: csourceRegistrations/{registrationId}"},"subsections":[{"section":{"id":"tabdescription-67","level":"3","number":"11.9.1","path":"11-tabapi-http-binding.html#tabdescription-67","title":"6.9.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-5","level":"3","number":"11.9.2","path":"11-tabapi-http-binding.html#tabresource-definition-5","title":"6.9.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-5","level":"3","number":"11.9.3","path":"11-tabapi-http-binding.html#tabresource-methods-5","title":"6.9.3 Resource methods"},"subsections":[{"section":{"id":"tabget-3","level":"4","number":"11.9.3.1","path":"11-tabapi-http-binding.html#tabget-3","title":"6.9.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-3","level":"4","number":"11.9.3.2","path":"11-tabapi-http-binding.html#tabpatch-3","title":"6.9.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-3","level":"4","number":"11.9.3.3","path":"11-tabapi-http-binding.html#tabdelete-3","title":"6.9.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptions","level":"2","number":"11.10","path":"11-tabapi-http-binding.html#tabresource-subscriptions","title":"6.10 Resource: subscriptions/"},"subsections":[{"section":{"id":"tabdescription-68","level":"3","number":"11.10.1","path":"11-tabapi-http-binding.html#tabdescription-68","title":"6.10.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-6","level":"3","number":"11.10.2","path":"11-tabapi-http-binding.html#tabresource-definition-6","title":"6.10.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-6","level":"3","number":"11.10.3","path":"11-tabapi-http-binding.html#tabresource-methods-6","title":"6.10.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-3","level":"4","number":"11.10.3.1","path":"11-tabapi-http-binding.html#tabpost-3","title":"6.10.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-4","level":"4","number":"11.10.3.2","path":"11-tabapi-http-binding.html#tabget-4","title":"6.10.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptionssubscriptionid","level":"2","number":"11.11","path":"11-tabapi-http-binding.html#tabresource-subscriptionssubscriptionid","title":"6.11 Resource: subscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-69","level":"3","number":"11.11.1","path":"11-tabapi-http-binding.html#tabdescription-69","title":"6.11.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-7","level":"3","number":"11.11.2","path":"11-tabapi-http-binding.html#tabresource-definition-7","title":"6.11.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-7","level":"3","number":"11.11.3","path":"11-tabapi-http-binding.html#tabresource-methods-7","title":"6.11.3 Resource methods"},"subsections":[{"section":{"id":"tabget-5","level":"4","number":"11.11.3.1","path":"11-tabapi-http-binding.html#tabget-5","title":"6.11.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-4","level":"4","number":"11.11.3.2","path":"11-tabapi-http-binding.html#tabpatch-4","title":"6.11.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-4","level":"4","number":"11.11.3.3","path":"11-tabapi-http-binding.html#tabdelete-4","title":"6.11.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptions","level":"2","number":"11.12","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptions","title":"6.12 Resource: csourceSubscriptions/"},"subsections":[{"section":{"id":"tabdescription-70","level":"3","number":"11.12.1","path":"11-tabapi-http-binding.html#tabdescription-70","title":"6.12.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-8","level":"3","number":"11.12.2","path":"11-tabapi-http-binding.html#tabresource-definition-8","title":"6.12.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-8","level":"3","number":"11.12.3","path":"11-tabapi-http-binding.html#tabresource-methods-8","title":"6.12.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-4","level":"4","number":"11.12.3.1","path":"11-tabapi-http-binding.html#tabpost-4","title":"6.12.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-6","level":"4","number":"11.12.3.2","path":"11-tabapi-http-binding.html#tabget-6","title":"6.12.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptionssubscriptionid","level":"2","number":"11.13","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptionssubscriptionid","title":"6.13 Resource: csourceSubscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-71","level":"3","number":"11.13.1","path":"11-tabapi-http-binding.html#tabdescription-71","title":"6.13.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-9","level":"3","number":"11.13.2","path":"11-tabapi-http-binding.html#tabresource-definition-9","title":"6.13.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-9","level":"3","number":"11.13.3","path":"11-tabapi-http-binding.html#tabresource-methods-9","title":"6.13.3 Resource methods"},"subsections":[{"section":{"id":"tabget-7","level":"4","number":"11.13.3.1","path":"11-tabapi-http-binding.html#tabget-7","title":"6.13.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-5","level":"4","number":"11.13.3.2","path":"11-tabapi-http-binding.html#tabpatch-5","title":"6.13.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-5","level":"4","number":"11.13.3.3","path":"11-tabapi-http-binding.html#tabdelete-5","title":"6.13.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationscreate","level":"2","number":"11.14","path":"11-tabapi-http-binding.html#tabresource-entityoperationscreate","title":"6.14 Resource: entityOperations/create"},"subsections":[{"section":{"id":"tabdescription-72","level":"3","number":"11.14.1","path":"11-tabapi-http-binding.html#tabdescription-72","title":"6.14.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-10","level":"3","number":"11.14.2","path":"11-tabapi-http-binding.html#tabresource-definition-10","title":"6.14.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-10","level":"3","number":"11.14.3","path":"11-tabapi-http-binding.html#tabresource-methods-10","title":"6.14.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-5","level":"4","number":"11.14.3.1","path":"11-tabapi-http-binding.html#tabpost-5","title":"6.14.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupsert","level":"2","number":"11.15","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupsert","title":"6.15 Resource: entityOperations/upsert"},"subsections":[{"section":{"id":"tabdescription-73","level":"3","number":"11.15.1","path":"11-tabapi-http-binding.html#tabdescription-73","title":"6.15.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-11","level":"3","number":"11.15.2","path":"11-tabapi-http-binding.html#tabresource-definition-11","title":"6.15.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-11","level":"3","number":"11.15.3","path":"11-tabapi-http-binding.html#tabresource-methods-11","title":"6.15.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-6","level":"4","number":"11.15.3.1","path":"11-tabapi-http-binding.html#tabpost-6","title":"6.15.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupdate","level":"2","number":"11.16","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupdate","title":"6.16 Resource: entityOperations/update"},"subsections":[{"section":{"id":"tabdescription-74","level":"3","number":"11.16.1","path":"11-tabapi-http-binding.html#tabdescription-74","title":"6.16.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-12","level":"3","number":"11.16.2","path":"11-tabapi-http-binding.html#tabresource-definition-12","title":"6.16.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-12","level":"3","number":"11.16.3","path":"11-tabapi-http-binding.html#tabresource-methods-12","title":"6.16.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-7","level":"4","number":"11.16.3.1","path":"11-tabapi-http-binding.html#tabpost-7","title":"6.16.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsdelete","level":"2","number":"11.17","path":"11-tabapi-http-binding.html#tabresource-entityoperationsdelete","title":"6.17 Resource: entityOperations/delete"},"subsections":[{"section":{"id":"tabdescription-75","level":"3","number":"11.17.1","path":"11-tabapi-http-binding.html#tabdescription-75","title":"6.17.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-13","level":"3","number":"11.17.2","path":"11-tabapi-http-binding.html#tabresource-definition-13","title":"6.17.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-13","level":"3","number":"11.17.3","path":"11-tabapi-http-binding.html#tabresource-methods-13","title":"6.17.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-8","level":"4","number":"11.17.3.1","path":"11-tabapi-http-binding.html#tabpost-8","title":"6.17.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentities","level":"2","number":"11.18","path":"11-tabapi-http-binding.html#tabresource-temporalentities","title":"6.18 Resource: temporal/entities/"},"subsections":[{"section":{"id":"tabdescription-76","level":"3","number":"11.18.1","path":"11-tabapi-http-binding.html#tabdescription-76","title":"6.18.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-14","level":"3","number":"11.18.2","path":"11-tabapi-http-binding.html#tabresource-definition-14","title":"6.18.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-14","level":"3","number":"11.18.3","path":"11-tabapi-http-binding.html#tabresource-methods-14","title":"6.18.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-9","level":"4","number":"11.18.3.1","path":"11-tabapi-http-binding.html#tabpost-9","title":"6.18.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-8","level":"4","number":"11.18.3.2","path":"11-tabapi-http-binding.html#tabget-8","title":"6.18.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityid","level":"2","number":"11.19","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityid","title":"6.19 Resource: temporal/entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-77","level":"3","number":"11.19.1","path":"11-tabapi-http-binding.html#tabdescription-77","title":"6.19.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-15","level":"3","number":"11.19.2","path":"11-tabapi-http-binding.html#tabresource-definition-15","title":"6.19.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-15","level":"3","number":"11.19.3","path":"11-tabapi-http-binding.html#tabresource-methods-15","title":"6.19.3 Resource methods"},"subsections":[{"section":{"id":"tabget-9","level":"4","number":"11.19.3.1","path":"11-tabapi-http-binding.html#tabget-9","title":"6.19.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-6","level":"4","number":"11.19.3.2","path":"11-tabapi-http-binding.html#tabdelete-6","title":"6.19.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrs","level":"2","number":"11.20","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrs","title":"6.20 Resource: temporal/entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-78","level":"3","number":"11.20.1","path":"11-tabapi-http-binding.html#tabdescription-78","title":"6.20.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-16","level":"3","number":"11.20.2","path":"11-tabapi-http-binding.html#tabresource-definition-16","title":"6.20.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-16","level":"3","number":"11.20.3","path":"11-tabapi-http-binding.html#tabresource-methods-16","title":"6.20.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-10","level":"4","number":"11.20.3.1","path":"11-tabapi-http-binding.html#tabpost-10","title":"6.20.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid","level":"2","number":"11.21","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid","title":"6.21 Resource: temporal/entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-79","level":"3","number":"11.21.1","path":"11-tabapi-http-binding.html#tabdescription-79","title":"6.21.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-17","level":"3","number":"11.21.2","path":"11-tabapi-http-binding.html#tabresource-definition-17","title":"6.21.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-17","level":"3","number":"11.21.3","path":"11-tabapi-http-binding.html#tabresource-methods-17","title":"6.21.3 Resource methods"},"subsections":[{"section":{"id":"tabdelete-7","level":"4","number":"11.21.3.1","path":"11-tabapi-http-binding.html#tabdelete-7","title":"6.21.3.1 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid-instanceid","level":"2","number":"11.22","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid-instanceid","title":"6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId}"},"subsections":[{"section":{"id":"tabdescription-80","level":"3","number":"11.22.1","path":"11-tabapi-http-binding.html#tabdescription-80","title":"6.22.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-18","level":"3","number":"11.22.2","path":"11-tabapi-http-binding.html#tabresource-definition-18","title":"6.22.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-18","level":"3","number":"11.22.3","path":"11-tabapi-http-binding.html#tabresource-methods-18","title":"6.22.3 Resource methods"},"subsections":[{"section":{"id":"tabpatch-6","level":"4","number":"11.22.3.1","path":"11-tabapi-http-binding.html#tabpatch-6","title":"6.22.3.1 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-8","level":"4","number":"11.22.3.2","path":"11-tabapi-http-binding.html#tabdelete-8","title":"6.22.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsquery","level":"2","number":"11.23","path":"11-tabapi-http-binding.html#tabresource-entityoperationsquery","title":"6.23 Resource: entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-81","level":"3","number":"11.23.1","path":"11-tabapi-http-binding.html#tabdescription-81","title":"6.23.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-19","level":"3","number":"11.23.2","path":"11-tabapi-http-binding.html#tabresource-definition-19","title":"6.23.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-19","level":"3","number":"11.23.3","path":"11-tabapi-http-binding.html#tabresource-methods-19","title":"6.23.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-11","level":"4","number":"11.23.3.1","path":"11-tabapi-http-binding.html#tabpost-11","title":"6.23.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentityoperationsquery","level":"2","number":"11.24","path":"11-tabapi-http-binding.html#tabresource-temporalentityoperationsquery","title":"6.24 Resource: temporal/entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-82","level":"3","number":"11.24.1","path":"11-tabapi-http-binding.html#tabdescription-82","title":"6.24.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-20","level":"3","number":"11.24.2","path":"11-tabapi-http-binding.html#tabresource-definition-20","title":"6.24.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-20","level":"3","number":"11.24.3","path":"11-tabapi-http-binding.html#tabresource-methods-20","title":"6.24.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-12","level":"4","number":"11.24.3.1","path":"11-tabapi-http-binding.html#tabpost-12","title":"6.24.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-types","level":"2","number":"11.25","path":"11-tabapi-http-binding.html#tabresource-types","title":"6.25 Resource: types/"},"subsections":[{"section":{"id":"tabdescription-83","level":"3","number":"11.25.1","path":"11-tabapi-http-binding.html#tabdescription-83","title":"6.25.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-21","level":"3","number":"11.25.2","path":"11-tabapi-http-binding.html#tabresource-definition-21","title":"6.25.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-21","level":"3","number":"11.25.3","path":"11-tabapi-http-binding.html#tabresource-methods-21","title":"6.25.3 Resource methods"},"subsections":[{"section":{"id":"tabget-10","level":"4","number":"11.25.3.1","path":"11-tabapi-http-binding.html#tabget-10","title":"6.25.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-typestype","level":"2","number":"11.26","path":"11-tabapi-http-binding.html#tabresource-typestype","title":"6.26 Resource: types/{type}"},"subsections":[{"section":{"id":"tabdescription-84","level":"3","number":"11.26.1","path":"11-tabapi-http-binding.html#tabdescription-84","title":"6.26.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-22","level":"3","number":"11.26.2","path":"11-tabapi-http-binding.html#tabresource-definition-22","title":"6.26.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-22","level":"3","number":"11.26.3","path":"11-tabapi-http-binding.html#tabresource-methods-22","title":"6.26.3 Resource methods"},"subsections":[{"section":{"id":"tabget-11","level":"4","number":"11.26.3.1","path":"11-tabapi-http-binding.html#tabget-11","title":"6.26.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributes","level":"2","number":"11.27","path":"11-tabapi-http-binding.html#tabresource-attributes","title":"6.27 Resource: attributes/"},"subsections":[{"section":{"id":"tabdescription-85","level":"3","number":"11.27.1","path":"11-tabapi-http-binding.html#tabdescription-85","title":"6.27.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-23","level":"3","number":"11.27.2","path":"11-tabapi-http-binding.html#tabresource-definition-23","title":"6.27.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-23","level":"3","number":"11.27.3","path":"11-tabapi-http-binding.html#tabresource-methods-23","title":"6.27.3 Resource methods"},"subsections":[{"section":{"id":"tabget-12","level":"4","number":"11.27.3.1","path":"11-tabapi-http-binding.html#tabget-12","title":"6.27.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributesattrid","level":"2","number":"11.28","path":"11-tabapi-http-binding.html#tabresource-attributesattrid","title":"6.28 Resource: attributes/{attrId}"},"subsections":[{"section":{"id":"tabdescription-86","level":"3","number":"11.28.1","path":"11-tabapi-http-binding.html#tabdescription-86","title":"6.28.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-24","level":"3","number":"11.28.2","path":"11-tabapi-http-binding.html#tabresource-definition-24","title":"6.28.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-24","level":"3","number":"11.28.3","path":"11-tabapi-http-binding.html#tabresource-methods-24","title":"6.28.3 Resource methods"},"subsections":[{"section":{"id":"tabget-13","level":"4","number":"11.28.3.1","path":"11-tabapi-http-binding.html#tabget-13","title":"6.28.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontexts","level":"2","number":"11.29","path":"11-tabapi-http-binding.html#tabresource-jsonldcontexts","title":"6.29 Resource: jsonldContexts/"},"subsections":[{"section":{"id":"tabdescription-87","level":"3","number":"11.29.1","path":"11-tabapi-http-binding.html#tabdescription-87","title":"6.29.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-25","level":"3","number":"11.29.2","path":"11-tabapi-http-binding.html#tabresource-definition-25","title":"6.29.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-25","level":"3","number":"11.29.3","path":"11-tabapi-http-binding.html#tabresource-methods-25","title":"6.29.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-13","level":"4","number":"11.29.3.1","path":"11-tabapi-http-binding.html#tabpost-13","title":"6.29.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-14","level":"4","number":"11.29.3.2","path":"11-tabapi-http-binding.html#tabget-14","title":"6.29.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontextscontextid","level":"2","number":"11.30","path":"11-tabapi-http-binding.html#tabresource-jsonldcontextscontextid","title":"6.30 Resource: jsonldContexts/{contextId}"},"subsections":[{"section":{"id":"tabdescription-88","level":"3","number":"11.30.1","path":"11-tabapi-http-binding.html#tabdescription-88","title":"6.30.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-26","level":"3","number":"11.30.2","path":"11-tabapi-http-binding.html#tabresource-definition-26","title":"6.30.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-26","level":"3","number":"11.30.3","path":"11-tabapi-http-binding.html#tabresource-methods-26","title":"6.30.3 Resource methods"},"subsections":[{"section":{"id":"tabget-15","level":"4","number":"11.30.3.1","path":"11-tabapi-http-binding.html#tabget-15","title":"6.30.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-9","level":"4","number":"11.30.3.2","path":"11-tabapi-http-binding.html#tabdelete-9","title":"6.30.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsmerge","level":"2","number":"11.31","path":"11-tabapi-http-binding.html#tabresource-entityoperationsmerge","title":"6.31 Resource: entityOperations/merge"},"subsections":[{"section":{"id":"tabdescription-89","level":"3","number":"11.31.1","path":"11-tabapi-http-binding.html#tabdescription-89","title":"6.31.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-27","level":"3","number":"11.31.2","path":"11-tabapi-http-binding.html#tabresource-definition-27","title":"6.31.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-27","level":"3","number":"11.31.3","path":"11-tabapi-http-binding.html#tabresource-methods-27","title":"6.31.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-14","level":"4","number":"11.31.3.1","path":"11-tabapi-http-binding.html#tabpost-14","title":"6.31.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitymapsentitymapid","level":"2","number":"11.32","path":"11-tabapi-http-binding.html#tabresource-entitymapsentitymapid","title":"6.32 Resource: entityMaps/{entityMapId}"},"subsections":[{"section":{"id":"tabdescription-90","level":"3","number":"11.32.1","path":"11-tabapi-http-binding.html#tabdescription-90","title":"6.32.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-28","level":"3","number":"11.32.2","path":"11-tabapi-http-binding.html#tabresource-definition-28","title":"6.32.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-28","level":"3","number":"11.32.3","path":"11-tabapi-http-binding.html#tabresource-methods-28","title":"6.32.3 Resource methods"},"subsections":[{"section":{"id":"tabget-16","level":"4","number":"11.32.3.1","path":"11-tabapi-http-binding.html#tabget-16","title":"6.32.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-7","level":"4","number":"11.32.3.2","path":"11-tabapi-http-binding.html#tabpatch-7","title":"6.32.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-10","level":"4","number":"11.32.3.3","path":"11-tabapi-http-binding.html#tabdelete-10","title":"6.32.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-infosourceidentity","level":"2","number":"11.33","path":"11-tabapi-http-binding.html#tabresource-infosourceidentity","title":"6.33 Resource: info/sourceIdentity"},"subsections":[{"section":{"id":"tabdescription-91","level":"3","number":"11.33.1","path":"11-tabapi-http-binding.html#tabdescription-91","title":"6.33.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-29","level":"3","number":"11.33.2","path":"11-tabapi-http-binding.html#tabresource-definition-29","title":"6.33.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-29","level":"3","number":"11.33.3","path":"11-tabapi-http-binding.html#tabresource-methods-29","title":"6.33.3 Resource methods"},"subsections":[{"section":{"id":"tabget-17","level":"4","number":"11.33.3.1","path":"11-tabapi-http-binding.html#tabget-17","title":"6.33.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitymaps","level":"2","number":"11.34","path":"11-tabapi-http-binding.html#tabresource-entitymaps","title":"6.34 Resource: entityMaps"},"subsections":[{"section":{"id":"tabdescription-92","level":"3","number":"11.34.1","path":"11-tabapi-http-binding.html#tabdescription-92","title":"6.34.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-30","level":"3","number":"11.34.2","path":"11-tabapi-http-binding.html#tabresource-definition-30","title":"6.34.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-30","level":"3","number":"11.34.3","path":"11-tabapi-http-binding.html#tabresource-methods-30","title":"6.34.3 Resource methods"},"subsections":[{"section":{"id":"tabget-18","level":"4","number":"11.34.3.1","path":"11-tabapi-http-binding.html#tabget-18","title":"6.34.3.1 GET"},"subsections":[]},{"section":{"id":"tabpost-15","level":"4","number":"11.34.3.2","path":"11-tabapi-http-binding.html#tabpost-15","title":"6.34.3.2 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitymaps","level":"2","number":"11.35","path":"11-tabapi-http-binding.html#tabresource-temporalentitymaps","title":"6.35 Resource: temporal/entityMaps"},"subsections":[{"section":{"id":"tabdescription-93","level":"3","number":"11.35.1","path":"11-tabapi-http-binding.html#tabdescription-93","title":"6.35.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-31","level":"3","number":"11.35.2","path":"11-tabapi-http-binding.html#tabresource-definition-31","title":"6.35.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-31","level":"3","number":"11.35.3","path":"11-tabapi-http-binding.html#tabresource-methods-31","title":"6.35.3 Resource methods"},"subsections":[{"section":{"id":"tabget-19","level":"4","number":"11.35.3.1","path":"11-tabapi-http-binding.html#tabget-19","title":"6.35.3.1 GET"},"subsections":[]},{"section":{"id":"tabpost-16","level":"4","number":"11.35.3.2","path":"11-tabapi-http-binding.html#tabpost-16","title":"6.35.3.2 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshots","level":"2","number":"11.36","path":"11-tabapi-http-binding.html#tabresource-snapshots","title":"6.36 Resource: snapshots"},"subsections":[{"section":{"id":"tabdescription-94","level":"3","number":"11.36.1","path":"11-tabapi-http-binding.html#tabdescription-94","title":"6.36.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-32","level":"3","number":"11.36.2","path":"11-tabapi-http-binding.html#tabresource-definition-32","title":"6.36.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-32","level":"3","number":"11.36.3","path":"11-tabapi-http-binding.html#tabresource-methods-32","title":"6.36.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-17","level":"4","number":"11.36.3.1","path":"11-tabapi-http-binding.html#tabpost-17","title":"6.36.3.1 POST"},"subsections":[]},{"section":{"id":"tabdelete-11","level":"4","number":"11.36.3.2","path":"11-tabapi-http-binding.html#tabdelete-11","title":"6.36.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshotssnapshotid","level":"2","number":"11.37","path":"11-tabapi-http-binding.html#tabresource-snapshotssnapshotid","title":"6.37 Resource: snapshots/{snapshotId}"},"subsections":[{"section":{"id":"tabdescription-95","level":"3","number":"11.37.1","path":"11-tabapi-http-binding.html#tabdescription-95","title":"6.37.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-33","level":"3","number":"11.37.2","path":"11-tabapi-http-binding.html#tabresource-definition-33","title":"6.37.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-33","level":"3","number":"11.37.3","path":"11-tabapi-http-binding.html#tabresource-methods-33","title":"6.37.3 Resource methods"},"subsections":[{"section":{"id":"tabget-20","level":"4","number":"11.37.3.1","path":"11-tabapi-http-binding.html#tabget-20","title":"6.37.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-8","level":"4","number":"11.37.3.2","path":"11-tabapi-http-binding.html#tabpatch-8","title":"6.37.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-12","level":"4","number":"11.37.3.3","path":"11-tabapi-http-binding.html#tabdelete-12","title":"6.37.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshotssnapshotidclone","level":"2","number":"11.38","path":"11-tabapi-http-binding.html#tabresource-snapshotssnapshotidclone","title":"6.38 Resource: snapshots/{snapshotId}/clone"},"subsections":[{"section":{"id":"tabdescription-96","level":"3","number":"11.38.1","path":"11-tabapi-http-binding.html#tabdescription-96","title":"6.38.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-34","level":"3","number":"11.38.2","path":"11-tabapi-http-binding.html#tabresource-definition-34","title":"6.38.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-34","level":"3","number":"11.38.3","path":"11-tabapi-http-binding.html#tabresource-methods-34","title":"6.38.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-18","level":"4","number":"11.38.3.1","path":"11-tabapi-http-binding.html#tabpost-18","title":"6.38.3.1 POST"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-mqtt-notification-binding","level":"1","number":"12","path":"12-tabapi-mqtt-notification-binding.html#tabapi-mqtt-notification-binding","title":"7 API MQTT Notification Binding"},"subsections":[{"section":{"id":"tabintroduction-23","level":"2","number":"12.1","path":"12-tabapi-mqtt-notification-binding.html#tabintroduction-23","title":"7.1 Introduction"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-3","level":"2","number":"12.2","path":"12-tabapi-mqtt-notification-binding.html#tabnotification-behaviour-3","title":"7.2 Notification behaviour"},"subsections":[]}]},{"section":{"id":"annex-a-normative-ngsi-ld-identifier-considerations","level":"1","number":"13","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#annex-a-normative-ngsi-ld-identifier-considerations","title":"Annex A (normative): NGSI-LD identifier considerations"},"subsections":[{"section":{"id":"a.1tabintroduction","level":"2","number":"13.1","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.1tabintroduction","title":"A.1 Introduction"},"subsections":[]},{"section":{"id":"a.2tabentity-identifiers","level":"2","number":"13.2","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.2tabentity-identifiers","title":"A.2 Entity identifiers"},"subsections":[]},{"section":{"id":"a.3tabngsi-ld-namespace","level":"2","number":"13.3","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.3tabngsi-ld-namespace","title":"A.3 NGSI-LD namespace"},"subsections":[]}]},{"section":{"id":"annex-b-normative-core-ngsi-ld-context-definition","level":"1","number":"14","path":"14-annex-b-normative-core-ngsi-ld-context-definition.html#annex-b-normative-core-ngsi-ld-context-definition","title":"Annex B (normative): Core NGSI-LD @context definition"},"subsections":[]},{"section":{"id":"annex-c-informative-examples-of-using-the-api","level":"1","number":"15","path":"15-annex-c-informative-examples-of-using-the-api.html#annex-c-informative-examples-of-using-the-api","title":"Annex C (informative): Examples of using the API"},"subsections":[{"section":{"id":"c.1tabintroduction","level":"2","number":"15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.1tabintroduction","title":"C.1 Introduction"},"subsections":[]},{"section":{"id":"c.2tabentity-representation","level":"2","number":"15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2tabentity-representation","title":"C.2 Entity Representation"},"subsections":[{"section":{"id":"c.2.1tabproperty-graph","level":"3","number":"15.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.1tabproperty-graph","title":"C.2.1 Property Graph"},"subsections":[]},{"section":{"id":"c.2.2tabvehicle-entity","level":"3","number":"15.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.2tabvehicle-entity","title":"C.2.2 Vehicle Entity"},"subsections":[]},{"section":{"id":"c.2.3tabparking-entity","level":"3","number":"15.2.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.3tabparking-entity","title":"C.2.3 Parking Entity"},"subsections":[]},{"section":{"id":"c.2.4tabcontext","level":"3","number":"15.2.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.4tabcontext","title":"C.2.4 @context"},"subsections":[]}]},{"section":{"id":"c.3tabcontext-source-registration","level":"2","number":"15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.3tabcontext-source-registration","title":"C.3 Context Source Registration"},"subsections":[]},{"section":{"id":"c.4tabcontext-subscription","level":"2","number":"15.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.4tabcontext-subscription","title":"C.4 Context Subscription"},"subsections":[]},{"section":{"id":"c.5tabhttp-rest-api-examples","level":"2","number":"15.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5tabhttp-rest-api-examples","title":"C.5 HTTP REST API Examples"},"subsections":[{"section":{"id":"c.5.1tabintroduction","level":"3","number":"15.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.1tabintroduction","title":"C.5.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.2tabcreate-entity-of-type-vehicle","level":"3","number":"15.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2tabcreate-entity-of-type-vehicle","title":"C.5.2 Create Entity of Type Vehicle"},"subsections":[{"section":{"id":"c.5.2.1tabhttp-request","level":"4","number":"15.5.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.1tabhttp-request","title":"C.5.2.1 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.2.2tabhttp-response","level":"4","number":"15.5.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.2tabhttp-response","title":"C.5.2.2 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.3tabquery-entities","level":"3","number":"15.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3tabquery-entities","title":"C.5.3 Query Entities"},"subsections":[{"section":{"id":"c.5.3.1tabintroduction","level":"4","number":"15.5.3.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.1tabintroduction","title":"C.5.3.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.3.2tabhttp-request","level":"4","number":"15.5.3.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.2tabhttp-request","title":"C.5.3.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.3.3tabhttp-response","level":"4","number":"15.5.3.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.3tabhttp-response","title":"C.5.3.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.4tabquery-entities-pagination","level":"3","number":"15.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4tabquery-entities-pagination","title":"C.5.4 Query Entities (Pagination)"},"subsections":[{"section":{"id":"c.5.4.1tabintroduction","level":"4","number":"15.5.4.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.1tabintroduction","title":"C.5.4.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.4.2tabhttp-request","level":"4","number":"15.5.4.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.2tabhttp-request","title":"C.5.4.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.4.3tabhttp-response","level":"4","number":"15.5.4.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.3tabhttp-response","title":"C.5.4.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.5tabtemporal-query","level":"3","number":"15.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5tabtemporal-query","title":"C.5.5 Temporal Query"},"subsections":[{"section":{"id":"c.5.5.1tabintroduction","level":"4","number":"15.5.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.1tabintroduction","title":"C.5.5.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.5.2tabhttp-request-1","level":"4","number":"15.5.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.2tabhttp-request-1","title":"C.5.5.2 HTTP Request #1"},"subsections":[]},{"section":{"id":"c.5.5.3tabhttp-response-1","level":"4","number":"15.5.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.3tabhttp-response-1","title":"C.5.5.3 HTTP Response #1"},"subsections":[]},{"section":{"id":"c.5.5.4tabhttp-request-2","level":"4","number":"15.5.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.4tabhttp-request-2","title":"C.5.5.4 HTTP Request #2"},"subsections":[]},{"section":{"id":"c.5.5.5tabhttp-response-2","level":"4","number":"15.5.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.5tabhttp-response-2","title":"C.5.5.5 HTTP Response #2"},"subsections":[]}]},{"section":{"id":"c.5.6tabtemporal-query-simplified-representation","level":"3","number":"15.5.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6tabtemporal-query-simplified-representation","title":"C.5.6 Temporal Query (Simplified Representation)"},"subsections":[{"section":{"id":"c.5.6.1tabintroduction","level":"4","number":"15.5.6.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.1tabintroduction","title":"C.5.6.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.6.2tabhttp-request","level":"4","number":"15.5.6.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.2tabhttp-request","title":"C.5.6.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.6.3tabhttp-response","level":"4","number":"15.5.6.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.3tabhttp-response","title":"C.5.6.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.7tabretrieve-available-entity-types","level":"3","number":"15.5.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7tabretrieve-available-entity-types","title":"C.5.7 Retrieve Available Entity Types"},"subsections":[{"section":{"id":"c.5.7.1tabintroduction","level":"4","number":"15.5.7.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.1tabintroduction","title":"C.5.7.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.7.2tabhttp-request","level":"4","number":"15.5.7.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.2tabhttp-request","title":"C.5.7.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.7.3tabhttp-response","level":"4","number":"15.5.7.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.3tabhttp-response","title":"C.5.7.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.8tabretrieve-details-of-available-entity-types","level":"3","number":"15.5.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8tabretrieve-details-of-available-entity-types","title":"C.5.8 Retrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"c.5.8.1tabintroduction","level":"4","number":"15.5.8.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.1tabintroduction","title":"C.5.8.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.8.2tabhttp-request","level":"4","number":"15.5.8.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.2tabhttp-request","title":"C.5.8.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.8.3tabhttp-response","level":"4","number":"15.5.8.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.3tabhttp-response","title":"C.5.8.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.9tabretrieve-available-entity-type-information","level":"3","number":"15.5.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9tabretrieve-available-entity-type-information","title":"C.5.9 Retrieve Available Entity Type Information"},"subsections":[{"section":{"id":"c.5.9.1tabintroduction","level":"4","number":"15.5.9.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.1tabintroduction","title":"C.5.9.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.9.2tabhttp-request","level":"4","number":"15.5.9.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.2tabhttp-request","title":"C.5.9.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.9.3tabhttp-response","level":"4","number":"15.5.9.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.3tabhttp-response","title":"C.5.9.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.10tabretrieve-available-attributes","level":"3","number":"15.5.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10tabretrieve-available-attributes","title":"C.5.10 Retrieve Available Attributes"},"subsections":[{"section":{"id":"c.5.10.1tabintroduction","level":"4","number":"15.5.10.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.1tabintroduction","title":"C.5.10.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.10.2tabhttp-request","level":"4","number":"15.5.10.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.2tabhttp-request","title":"C.5.10.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.10.3tabhttp-response","level":"4","number":"15.5.10.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.3tabhttp-response","title":"C.5.10.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.11tabretrieve-details-of-available-attributes","level":"3","number":"15.5.11","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11tabretrieve-details-of-available-attributes","title":"C.5.11 Retrieve Details of Available Attributes"},"subsections":[{"section":{"id":"c.5.11.1tabintroduction","level":"4","number":"15.5.11.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.1tabintroduction","title":"C.5.11.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.11.2tabhttp-request","level":"4","number":"15.5.11.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.2tabhttp-request","title":"C.5.11.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.11.3tabhttp-response","level":"4","number":"15.5.11.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.3tabhttp-response","title":"C.5.11.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.12tabretrieve-available-attribute-information","level":"3","number":"15.5.12","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12tabretrieve-available-attribute-information","title":"C.5.12 Retrieve Available Attribute Information"},"subsections":[{"section":{"id":"c.5.12.1tabintroduction","level":"4","number":"15.5.12.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.1tabintroduction","title":"C.5.12.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.12.2tabhttp-request","level":"4","number":"15.5.12.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.2tabhttp-request","title":"C.5.12.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.12.3tabhttp-response","level":"4","number":"15.5.12.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.3tabhttp-response","title":"C.5.12.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.13tabquery-entities-natural-language-filtering","level":"3","number":"15.5.13","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13tabquery-entities-natural-language-filtering","title":"C.5.13 Query Entities (Natural Language Filtering)"},"subsections":[{"section":{"id":"c.5.13.1tabintroduction","level":"4","number":"15.5.13.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.1tabintroduction","title":"C.5.13.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.13.2tabhttp-request","level":"4","number":"15.5.13.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.2tabhttp-request","title":"C.5.13.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.13.3tabhttp-response","level":"4","number":"15.5.13.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.3tabhttp-response","title":"C.5.13.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.14tabtemporal-query-aggregated-representation","level":"3","number":"15.5.14","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14tabtemporal-query-aggregated-representation","title":"C.5.14 Temporal Query (Aggregated Representation)"},"subsections":[{"section":{"id":"c.5.14.1tabintroduction","level":"4","number":"15.5.14.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.1tabintroduction","title":"C.5.14.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.14.2tabhttp-request","level":"4","number":"15.5.14.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.2tabhttp-request","title":"C.5.14.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.14.3tabhttp-response","level":"4","number":"15.5.14.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.3tabhttp-response","title":"C.5.14.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.15tabscope-queries","level":"3","number":"15.5.15","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15tabscope-queries","title":"C.5.15 Scope Queries"},"subsections":[{"section":{"id":"c.5.15.1tabintroduction","level":"4","number":"15.5.15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.1tabintroduction","title":"C.5.15.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.15.2tabhttp-request","level":"4","number":"15.5.15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.2tabhttp-request","title":"C.5.15.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.15.3tabhttp-response","level":"4","number":"15.5.15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.3tabhttp-response","title":"C.5.15.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.16tabtemporal-scope-queries","level":"3","number":"15.5.16","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16tabtemporal-scope-queries","title":"C.5.16 Temporal Scope Queries"},"subsections":[{"section":{"id":"c.5.16.1tabintroduction","level":"4","number":"15.5.16.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.1tabintroduction","title":"C.5.16.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.16.2tabhttp-request","level":"4","number":"15.5.16.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.2tabhttp-request","title":"C.5.16.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.16.3tabhttp-response","level":"4","number":"15.5.16.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.3tabhttp-response","title":"C.5.16.3 HTTP Response"},"subsections":[]}]}]},{"section":{"id":"c.6tabdate-representation","level":"2","number":"15.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.6tabdate-representation","title":"C.6 Date Representation"},"subsections":[]},{"section":{"id":"c.7tabcontext-utilization-clarifications","level":"2","number":"15.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.7tabcontext-utilization-clarifications","title":"C.7 @context utilization clarifications"},"subsections":[]},{"section":{"id":"c.8tablink-header-utilization-clarifications","level":"2","number":"15.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.8tablink-header-utilization-clarifications","title":"C.8 Link header utilization clarifications"},"subsections":[]},{"section":{"id":"c.9tabcontext-processing-clarifications","level":"2","number":"15.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.9tabcontext-processing-clarifications","title":"C.9 @context processing clarifications"},"subsections":[]},{"section":{"id":"c.10tabvaluetype-datatype-utilization-clarifications","level":"2","number":"15.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.10tabvaluetype-datatype-utilization-clarifications","title":"C.10 ValueType datatype utilization clarifications"},"subsections":[]},{"section":{"id":"c.11tabentity-with-digital-signature-for-a-property","level":"2","number":"15.11","path":"15-annex-c-informative-examples-of-using-the-api.html#c.11tabentity-with-digital-signature-for-a-property","title":"C.11 Entity with digital signature for a Property"},"subsections":[]}]},{"section":{"id":"annex-d-informative-transformation-algorithms","level":"1","number":"16","path":"16-annex-d-informative-transformation-algorithms.html#annex-d-informative-transformation-algorithms","title":"Annex D (informative): Transformation Algorithms"},"subsections":[{"section":{"id":"d.1tabintroduction","level":"2","number":"16.1","path":"16-annex-d-informative-transformation-algorithms.html#d.1tabintroduction","title":"D.1 Introduction"},"subsections":[]},{"section":{"id":"d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","level":"2","number":"16.2","path":"16-annex-d-informative-transformation-algorithms.html#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","title":"D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)"},"subsections":[]},{"section":{"id":"d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","level":"2","number":"16.3","path":"16-annex-d-informative-transformation-algorithms.html#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","title":"D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1)"},"subsections":[]},{"section":{"id":"d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","level":"2","number":"16.4","path":"16-annex-d-informative-transformation-algorithms.html#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","title":"D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2)"},"subsections":[]}]},{"section":{"id":"annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","level":"1","number":"17","path":"17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","title":"Annex E (informative): RDF-compatible specification of NGSI-LD meta-model"},"subsections":[]},{"section":{"id":"annex-f-informative-conventions-and-syntax-guidelines","level":"1","number":"18","path":"18-annex-f-informative-conventions-and-syntax-guidelines.html#annex-f-informative-conventions-and-syntax-guidelines","title":"Annex F (informative): Conventions and syntax guidelines"},"subsections":[]},{"section":{"id":"annex-g-informative-localization-and-internationalization-support","level":"1","number":"19","path":"19-annex-g-informative-localization-and-internationalization-support.html#annex-g-informative-localization-and-internationalization-support","title":"Annex G (informative): Localization and Internationalization Support"},"subsections":[{"section":{"id":"g.0tabforeword","level":"2","number":"19.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.0tabforeword","title":"G.0 Foreword"},"subsections":[]},{"section":{"id":"g.1tabintroduction","level":"2","number":"19.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1tabintroduction","title":"G.1 Introduction"},"subsections":[{"section":{"id":"g.1.0tabforeword","level":"3","number":"19.2.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.0tabforeword","title":"G.1.0 Foreword"},"subsections":[]},{"section":{"id":"g.1.1tabassociating-an-entity-with-a-natural-language","level":"3","number":"19.2.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.1tabassociating-an-entity-with-a-natural-language","title":"G.1.1 Associating an Entity with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.2tabassociating-a-property-with-a-natural-language","level":"3","number":"19.2.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.2tabassociating-a-property-with-a-natural-language","title":"G.1.2 Associating a Property with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.3tabassociating-as-equivalent-entity","level":"3","number":"19.2.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.3tabassociating-as-equivalent-entity","title":"G.1.3 Associating as equivalent entity"},"subsections":[]}]},{"section":{"id":"g.2tabnatural-language-collation-support","level":"2","number":"19.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2tabnatural-language-collation-support","title":"G.2 Natural Language Collation Support"},"subsections":[{"section":{"id":"g.2.0tabforeword","level":"3","number":"19.3.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.0tabforeword","title":"G.2.0 Foreword"},"subsections":[]},{"section":{"id":"g.2.1tabmaintain-collations-as-metadata","level":"3","number":"19.3.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.1tabmaintain-collations-as-metadata","title":"G.2.1 Maintain collations as metadata"},"subsections":[]},{"section":{"id":"g.2.2tabroute-language-sensitive-queries-via-a-proxy","level":"3","number":"19.3.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.2tabroute-language-sensitive-queries-via-a-proxy","title":"G.2.2 Route language sensitive queries via a proxy"},"subsections":[]}]},{"section":{"id":"g.3tablocalization-of-dates-currency-formats-etc.","level":"2","number":"19.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3tablocalization-of-dates-currency-formats-etc.","title":"G.3 Localization of Dates, Currency formats, etc."},"subsections":[{"section":{"id":"g.3.0tabforeword","level":"3","number":"19.4.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.0tabforeword","title":"G.3.0 Foreword"},"subsections":[]},{"section":{"id":"g.3.1tablocalizing-dates","level":"3","number":"19.4.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.1tablocalizing-dates","title":"G.3.1 Localizing Dates"},"subsections":[]}]}]},{"section":{"id":"annex-h-informative-suggested-actuation-workflows","level":"1","number":"20","path":"20-annex-h-informative-suggested-actuation-workflows.html#annex-h-informative-suggested-actuation-workflows","title":"Annex H (informative): Suggested actuation workflows"},"subsections":[{"section":{"id":"h.1tabactuators-and-feedback-to-the-consumer","level":"2","number":"20.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.1tabactuators-and-feedback-to-the-consumer","title":"H.1 Actuators and feedback to the consumer"},"subsections":[]},{"section":{"id":"h.2tabarchitecture-for-actuation","level":"2","number":"20.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.2tabarchitecture-for-actuation","title":"H.2 Architecture for actuation"},"subsections":[]},{"section":{"id":"h.3tabstructure-of-commands-and-additional-properties","level":"2","number":"20.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3tabstructure-of-commands-and-additional-properties","title":"H.3 Structure of Commands and additional Properties"},"subsections":[{"section":{"id":"h.3.0tabintroduction","level":"3","number":"20.3.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.0tabintroduction","title":"H.3.0 Introduction"},"subsections":[]},{"section":{"id":"h.3.1tabproperty-for-listing-available-commands","level":"3","number":"20.3.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.1tabproperty-for-listing-available-commands","title":"H.3.1 Property for listing available commands"},"subsections":[]},{"section":{"id":"h.3.2tabproperties-for-command-endpoints","level":"3","number":"20.3.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.2tabproperties-for-command-endpoints","title":"H.3.2 Properties for command endpoints"},"subsections":[]}]},{"section":{"id":"h.4tabcommunication-model","level":"2","number":"20.4","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4tabcommunication-model","title":"H.4 Communication model"},"subsections":[{"section":{"id":"h.4.1tabpossible-communication-models","level":"3","number":"20.4.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.1tabpossible-communication-models","title":"H.4.1 Possible communication models"},"subsections":[]},{"section":{"id":"h.4.2tabsubscriptionnotification-model","level":"3","number":"20.4.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.2tabsubscriptionnotification-model","title":"H.4.2 Subscription/notification model"},"subsections":[]},{"section":{"id":"h.4.3tabforwarding-model","level":"3","number":"20.4.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.3tabforwarding-model","title":"H.4.3 Forwarding model"},"subsections":[]}]},{"section":{"id":"h.5tabimplementation-of-the-subscription-based-actuation-workflow","level":"2","number":"20.5","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.5tabimplementation-of-the-subscription-based-actuation-workflow","title":"H.5 Implementation of the subscription-based actuation workflow"},"subsections":[]},{"section":{"id":"h.6tabimplementation-of-the-registration-based-actuation-workflow","level":"2","number":"20.6","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.6tabimplementation-of-the-registration-based-actuation-workflow","title":"H.6 Implementation of the registration-based actuation workflow"},"subsections":[]}]},{"section":{"id":"annex-i-informative-change-history","level":"1","number":"21","path":"21-annex-i-informative-change-history.html#annex-i-informative-change-history","title":"Annex I (informative): Change history"},"subsections":[]},{"section":{"id":"history","level":"1","number":"22","path":"22-history.html#history","title":"History"},"subsections":[]}]} \ No newline at end of file diff --git a/API-md/0--1.md b/API-md/0--1.md deleted file mode 100644 index de6f4e5e219aff6b0eca3cead000253a90c88981..0000000000000000000000000000000000000000 --- a/API-md/0--1.md +++ /dev/null @@ -1,1991 +0,0 @@ -::: ZA -[ETSI GS CIM 009 ]{.ondemand_CHAR_size_32}V1.9.1[(2025-06)]{.ondemand_CHAR_size_16} -::: - -::: ZT -Context Information Management (CIM); -::: - -::: ZT -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.]{.ondemand_CHAR_name_Arial_size_9}[It does not necessarily represent the views of the entire ETSI membership.]{.ondemand_CHAR_name_Arial_size_9} - -::: ZB -**[Group Specification]{.ondemand_CHAR_name_Century_Gothic_size_16_color_FFFFFF}** -::: - -Reference - -[RGS/CIM-009]{.ondemand_CHAR_name_Arial_size_9}[v]{.ondemand_CHAR_name_Arial_size_9}[191]{.ondemand_CHAR_name_Arial_size_9} - -Keywords - -[API, architecture, digital twins, GAP, information model, interoperability, NGSI-LD, smart agriculture, smart city, smart industry, smart manufacturing, smart water, WoT]{.ondemand_CHAR_name_Arial_size_9} - -*ETSI* - -[650 Route des Lucioles]{.ondemand_CHAR_name_Arial_size_9} - -[F-06921 Sophia Antipolis Cedex - FRANCE]{.ondemand_CHAR_name_Arial_size_9} - -[Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16]{.ondemand_CHAR_name_Arial_size_9} - -[Siret N° 348 623 562 00017 - ]{.ondemand_CHAR_name_Arial_size_7}[APE 7112B]{.ondemand_CHAR_name_Arial_size_7} - -[Association à but non lucratif enregistrée à la]{.ondemand_CHAR_name_Arial_size_7} - -[Sous-Préfecture de Grasse (06) N° ]{.ondemand_CHAR_name_Arial_size_7}[w061004871]{.ondemand_CHAR_name_Arial_size_7} - -*Important notice* - -[The present document can be downloaded from the]{.ondemand_CHAR_name_Arial_size_9}[@#! Hyperlink ETSI Search & Browse Standards@#!](https://www.etsi.org/standards-search)[application.]{.Hyperlink} - -[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 ]{.ondemand_CHAR_name_Arial_size_9}[ETSI deliver](http://www.etsi.org/deliver)[repository]{.Hyperlink}[.]{.ondemand_CHAR_name_Arial_size_9} - -[Users should be aware that the present document may be revised or have its status changed, ]{.ondemand_CHAR_name_Arial_size_9}[this information is available ]{.ondemand_CHAR_name_Arial_size_9}[in the ]{.ondemand_CHAR_name_Arial_size_9}[Milestones listing](https://portal.etsi.org/Services/editHelp/Standards-development/Tracking-a-draft/Status-codes)[.]{.Hyperlink} - -[If you find errors in the present document, please send your comments to]{.ondemand_CHAR_name_Arial_size_9}[the relevant service listed under ]{.ondemand_CHAR_name_Arial_size_9}[Committee Support Staff](https://portal.etsi.org/People/Commitee-Support-Staff)[.]{.ondemand_CHAR_name_Arial_size_9} - -::: ondemand_PAR_alignment_CENTER -[If you find a security vulnerability in the present document, please report it through our ]{.ondemand_CHAR_name_Arial_size_9} -::: - -::: FL -[Coordinated Vulnerability Disclosure (CVD)](https://www.etsi.org/standards/coordinated-vulnerability-disclosure)[program.]{.ondemand_CHAR_name_Arial_size_9} -::: - -*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 ]{.ondemand_CHAR_name_Arial_size_9} - -[other professional standard and applicable regulations. ]{.ondemand_CHAR_name_Arial_size_9} - -[No recommendation as to products and services or vendors is made or should be implied.]{.ondemand_CHAR_name_Arial_size_9} - -[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.]{.ondemand_CHAR_name_Arial_size_9} - -[In no event shall ETSI be held liable for loss of profits or any other incidental or consequential damages.]{.ondemand_CHAR_name_Arial_size_9} - -[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.]{.ondemand_CHAR_name_Arial_size_9} - -*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.]{.ondemand_CHAR_name_Arial_size_9}[The content of the PDF version shall not be modified without the written authorization of ETSI.]{.ondemand_CHAR_name_Arial_size_9}[The copyright and the foregoing restriction extend to reproduction in all media.]{.ondemand_CHAR_name_Arial_size_9} - -[© ETSI 2025.]{.ondemand_CHAR_name_Arial_size_9} - -[All rights reserved.]{.ondemand_CHAR_name_Arial_size_9} - -::: TT -Contents -::: - -Intellectual Property Rights [20](1-intellectual-property-rights.md#intellectual-property-rights) - -Foreword [20](2-foreword.md#foreword) - -Modal verbs terminology [20](3-modal-verbs-terminology.md#modal-verbs-terminology) - -Executive summary [20](4-executive-summary.md#executive-summary) - -Introduction [21](5-introduction.md#introduction) - -1 Scope [22](6-tabscope.md#tabscope) - -2 References [22](7-tabreferences.md#tabreferences) - -2.1 Normative references [22](7-tabreferences.md#tabnormative-references) - -2.2 Informative references [23](7-tabreferences.md#tabinformative-references) - -3 Definition of terms, symbols and abbreviations [24](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabdefinition-of-terms-symbols-and-abbreviations) - -3.1 Terms [24](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms) - -3.2 Symbols [27](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabsymbols) - -3.3 Abbreviations [27](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tababbreviations) - -4 Context Information Management Framework [29](9-tabcontext-information-management-framework.md#tabcontext-information-management-framework) - -4.1 Introduction [29](9-tabcontext-information-management-framework.md#tabintroduction) - -4.2 NGSI-LD Information Model [29](9-tabcontext-information-management-framework.md#tabngsi-ld-information-model) - -4.2.1 Introduction [29](9-tabcontext-information-management-framework.md#tabintroduction-1) - -4.2.2 NGSI-LD Meta Model [30](9-tabcontext-information-management-framework.md#tabngsi-ld-meta-model) - -4.2.3 Cross Domain Ontology [31](9-tabcontext-information-management-framework.md#tabcross-domain-ontology) - -4.2.4 NGSI-LD domain-specific models and instantiation [32](9-tabcontext-information-management-framework.md#tabngsi-ld-domain-specific-models-and-instantiation) - -4.2.5 UML representation [32](9-tabcontext-information-management-framework.md#tabuml-representation) - -4.3 NGSI-LD Architectural Considerations [33](9-tabcontext-information-management-framework.md#tabngsi-ld-architectural-considerations) - -4.3.1 Introduction [33](9-tabcontext-information-management-framework.md#tabintroduction-2) - -4.3.2 Centralized architecture [33](9-tabcontext-information-management-framework.md#tabcentralized-architecture) - -4.3.3 Distributed architecture [34](9-tabcontext-information-management-framework.md#tabdistributed-architecture) - -4.3.4 Federated architecture [35](9-tabcontext-information-management-framework.md#tabfederated-architecture) - -4.3.5 NGSI-LD API Structure and Implementation Options [36](9-tabcontext-information-management-framework.md#tabngsi-ld-api-structure-and-implementation-options) - -4.3.6 Distributed Operations [41](9-tabcontext-information-management-framework.md#tabdistributed-operations) - -4.3.6.1 Introduction [41](9-tabcontext-information-management-framework.md#tabintroduction-3) - -4.3.6.2 Additive Registrations [42](9-tabcontext-information-management-framework.md#tabadditive-registrations) - -4.3.6.3 Proxied Registrations [42](9-tabcontext-information-management-framework.md#tabproxied-registrations) - -4.3.6.4 Limiting Cascading Distributed Operations [43](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations) - -4.3.6.5 Extra information to provide when contacting Context Source [43](9-tabcontext-information-management-framework.md#tabextra-information-to-provide-when-contacting-context-source) - -4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source [43](9-tabcontext-information-management-framework.md#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source) - -4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations [44](9-tabcontext-information-management-framework.md#tabquerying-and-retrieving-distributed-entities-as-unitary-operations) - -4.3.6.8 Backwards compatibility of Context Source payloads [45](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads) - -4.3.7 Snapshots [46](9-tabcontext-information-management-framework.md#tabsnapshots) - -4.4 Core and user NGSI-LD \@context [47](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) - -4.5 NGSI-LD Data Representation [48](9-tabcontext-information-management-framework.md#tabngsi-ld-data-representation) - -4.5.0 Introduction [48](9-tabcontext-information-management-framework.md#tabintroduction-4) - -4.5.1 NGSI-LD Entity Representation [48](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation) - -4.5.2 NGSI-LD Property Representations [49](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations) - -4.5.2.1 Introduction [49](9-tabcontext-information-management-framework.md#tabintroduction-5) - -4.5.2.2 Normalized NGSI-LD Property [49](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property) - -4.5.2.3 Concise NGSI-LD Property [50](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property) - -4.5.3 NGSI-LD Relationship Representations [52](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations) - -4.5.3.1 Introduction [52](9-tabcontext-information-management-framework.md#tabintroduction-6) - -4.5.3.2 Normalized NGSI-LD Relationship [52](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship) - -4.5.3.3 Concise NGSI-LD Relationship [53](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship) - -4.5.4 Simplified Representation [55](9-tabcontext-information-management-framework.md#tabsimplified-representation) - -4.5.5 Multi-Attribute Support [60](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) - -4.5.5.1 Introduction [60](9-tabcontext-information-management-framework.md#tabintroduction-7) - -4.5.5.2 Processing of Conflicting Transient Entities [60](9-tabcontext-information-management-framework.md#tabprocessing-of-conflicting-transient-entities) - -4.5.5.3 Processing of Conflicting Attributes [60](9-tabcontext-information-management-framework.md#tabprocessing-of-conflicting-attributes) - -4.5.6 Temporal Representation of an Entity [61](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-an-entity) - -4.5.7 Temporal Representation of a Property [61](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property) - -4.5.8 Temporal Representation of a Relationship [61](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship) - -4.5.9 Simplified temporal representation of an Entity [61](9-tabcontext-information-management-framework.md#tabsimplified-temporal-representation-of-an-entity) - -4.5.10 Entity Type List Representation [65](9-tabcontext-information-management-framework.md#tabentity-type-list-representation) - -4.5.11 Detailed Entity Type List Representation [65](9-tabcontext-information-management-framework.md#tabdetailed-entity-type-list-representation) - -4.5.12 Entity Type Information Representation [66](9-tabcontext-information-management-framework.md#tabentity-type-information-representation) - -4.5.13 Attribute List Representation [66](9-tabcontext-information-management-framework.md#tabattribute-list-representation) - -4.5.14 Detailed Attribute List Representation [66](9-tabcontext-information-management-framework.md#tabdetailed-attribute-list-representation) - -4.5.15 Attribute Information Representation [66](9-tabcontext-information-management-framework.md#tabattribute-information-representation) - -4.5.16 GeoJSON Representation of Entities [67](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) - -4.5.16.0 Foreword [67](9-tabcontext-information-management-framework.md#tabforeword) - -4.5.16.1 Top-level "geometry" field selection algorithm [67](9-tabcontext-information-management-framework.md#tabtop-level-geometry-field-selection-algorithm) - -4.5.16.2 GeoJSON Representation of an individual Entity [67](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-an-individual-entity) - -4.5.16.3 GeoJSON Representation of Multiple Entities [68](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-multiple-entities) - -4.5.17 Simplified GeoJSON Representation of Entities [68](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-entities) - -4.5.17.0 Foreword [68](9-tabcontext-information-management-framework.md#tabforeword-1) - -4.5.17.1 Simplified GeoJSON Representation of an individual Entity [68](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-an-individual-entity) - -4.5.17.2 Simplified GeoJSON Representation of multiple Entities [69](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-multiple-entities) - -4.5.18 NGSI-LD LanguageProperty Representations [69](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations) - -4.5.18.1 Introduction [69](9-tabcontext-information-management-framework.md#tabintroduction-8) - -4.5.18.2 Normalized NGSI-LD LanguageProperty [69](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-languageproperty) - -4.5.18.3 Concise NGSI-LD LanguageProperty [70](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-languageproperty) - -4.5.19 Aggregated temporal representation of an Entity [71](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity) - -4.5.19.0 Foreword [71](9-tabcontext-information-management-framework.md#tabforeword-2) - -4.5.19.1 Supported behaviours for aggregation functions [71](9-tabcontext-information-management-framework.md#tabsupported-behaviours-for-aggregation-functions) - -4.5.20 NGSI-LD VocabProperty Representations [73](9-tabcontext-information-management-framework.md#tabngsi-ld-vocabproperty-representations) - -4.5.20.1 Introduction [73](9-tabcontext-information-management-framework.md#tabintroduction-9) - -4.5.20.2 Normalized NGSI-LD VocabProperty [73](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-vocabproperty) - -4.5.20.3 Concise NGSI-LD VocabProperty [74](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-vocabproperty) - -4.5.21 NGSI-LD ListProperty Representations [74](9-tabcontext-information-management-framework.md#tabngsi-ld-listproperty-representations) - -4.5.21.1 Introduction [74](9-tabcontext-information-management-framework.md#tabintroduction-10) - -4.5.21.2 Normalized NGSI-LD ListProperty [75](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-listproperty) - -4.5.21.3 Concise NGSI-LD ListProperty [75](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listproperty) - -4.5.22 NGSI-LD ListRelationship Representations [76](9-tabcontext-information-management-framework.md#tabngsi-ld-listrelationship-representations) - -4.5.22.1 Introduction [76](9-tabcontext-information-management-framework.md#tabintroduction-11) - -4.5.22.2 Normalized NGSI-LD ListRelationship [76](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-listrelationship) - -4.5.22.3 Concise NGSI-LD ListRelationship [76](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listrelationship) - -4.5.23 NGSI-LD Linked Entity Retrieval [77](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) - -4.5.23.1 Introduction [77](9-tabcontext-information-management-framework.md#tabintroduction-12) - -4.5.23.2 Inline Linked Entity Representation [77](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation) - -4.5.23.3 Flattened Linked Entity Representation [77](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation) - -4.5.24 NGSI-LD JsonProperty Representations [78](9-tabcontext-information-management-framework.md#tabngsi-ld-jsonproperty-representations) - -4.5.24.1 Introduction [78](9-tabcontext-information-management-framework.md#tabintroduction-13) - -4.5.24.2 Normalized NGSI-LD JsonProperty [78](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-jsonproperty) - -4.5.24.3 Concise NGSI-LD JsonProperty [78](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-jsonproperty) - -4.5.25 NGSI-LD EntityMap Representation [79](9-tabcontext-information-management-framework.md#tabngsi-ld-entitymap-representation) - -4.6 Data Representation Restrictions [79](9-tabcontext-information-management-framework.md#tabdata-representation-restrictions) - -4.6.1 Supported text encodings [79](9-tabcontext-information-management-framework.md#tabsupported-text-encodings) - -4.6.2 Supported names [79](9-tabcontext-information-management-framework.md#tabsupported-names) - -4.6.3 Supported data types for Values [80](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values) - -4.6.4 Supported Content [81](9-tabcontext-information-management-framework.md#tabsupported-content) - -4.6.5 Supported data types for LanguageMaps [81](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-languagemaps) - -4.6.6 Ordering of Entities in arrays having more than one instance of the same Entity [81](9-tabcontext-information-management-framework.md#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity) - -4.7 Geospatial Properties [82](9-tabcontext-information-management-framework.md#tabgeospatial-properties) - -4.7.1 GeoJSON Geometries [82](9-tabcontext-information-management-framework.md#tabgeojson-geometries) - -4.7.2 Representation of GeoJSON Geometries in JSON-LD [82](9-tabcontext-information-management-framework.md#tabrepresentation-of-geojson-geometries-in-json-ld) - -4.7.3 Concise NGSI-LD GeoProperty [83](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-geoproperty) - -4.8 Temporal Properties [83](9-tabcontext-information-management-framework.md#tabtemporal-properties) - -4.9 NGSI-LD Query Language [84](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) - -4.10 NGSI-LD Geoquery Language [91](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) - -4.11 NGSI-LD Temporal Query Language [93](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language) - -4.12 NGSI-LD Pagination [94](9-tabcontext-information-management-framework.md#tabngsi-ld-pagination) - -4.13 Counting the Number of Results [95](9-tabcontext-information-management-framework.md#tabcounting-the-number-of-results) - -4.14 Supporting Multiple Tenants [95](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants) - -4.15 NGSI-LD Language Filter [95](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) - -4.16 Supporting Multiple Entity Types [96](9-tabcontext-information-management-framework.md#tabsupporting-multiple-entity-types) - -4.17 NGSI-LD Entity Type Selection Language [96](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) - -4.18 NGSI-LD Scopes [97](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes) - -4.19 NGSI-LD Scope Query Language [97](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) - -4.20 NGSI-LD Distributed Operation names [98](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names) - -4.21 NGSI-LD Attribute Projection Language [100](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language) - -4.22 Transient Storage of Entities and Attributes [100](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes) - -4.23 Entity Ordering [101](9-tabcontext-information-management-framework.md#tabentity-ordering) - -4.23.1 Introduction [101](9-tabcontext-information-management-framework.md#tabintroduction-14) - -4.23.2 Datatype Comparison Order [101](9-tabcontext-information-management-framework.md#tabdatatype-comparison-order) - -4.23.3 NGSI-LD Entity Ordering Language [102](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-ordering-language) - -5 API Operation Definition [103](10-tabapi-operation-definition.md#tabapi-operation-definition) - -5.1 Introduction [103](10-tabapi-operation-definition.md#tabintroduction-15) - -5.2 Data Types [103](10-tabapi-operation-definition.md#tabdata-types) - -5.2.1 Introduction [103](10-tabapi-operation-definition.md#tabintroduction-16) - -5.2.2 Common members [103](10-tabapi-operation-definition.md#tabcommon-members) - -5.2.3 \@context [104](10-tabapi-operation-definition.md#tabcontext) - -5.2.4 Entity [104](10-tabapi-operation-definition.md#tabentity) - -5.2.5 Property [105](10-tabapi-operation-definition.md#tabproperty) - -5.2.6 Relationship [107](10-tabapi-operation-definition.md#tabrelationship) - -5.2.7 GeoProperty [109](10-tabapi-operation-definition.md#tabgeoproperty) - -5.2.8 EntityInfo [111](10-tabapi-operation-definition.md#tabentityinfo) - -5.2.9 CSourceRegistration [111](10-tabapi-operation-definition.md#tabcsourceregistration) - -5.2.10 RegistrationInfo [115](10-tabapi-operation-definition.md#tabregistrationinfo) - -5.2.11 TimeInterval [115](10-tabapi-operation-definition.md#tabtimeinterval) - -5.2.12 Subscription [116](10-tabapi-operation-definition.md#tabsubscription) - -5.2.13 GeoQuery [118](10-tabapi-operation-definition.md#tabgeoquery) - -5.2.14 NotificationParams [119](10-tabapi-operation-definition.md#tabnotificationparams) - -5.2.14.1 NotificationParams data type definition [119](10-tabapi-operation-definition.md#tabnotificationparams-data-type-definition) - -5.2.14.2 Output only members [120](10-tabapi-operation-definition.md#taboutput-only-members) - -5.2.15 Endpoint [121](10-tabapi-operation-definition.md#tabendpoint) - -5.2.16 BatchOperationResult [122](10-tabapi-operation-definition.md#tabbatchoperationresult) - -5.2.17 BatchEntityError [122](10-tabapi-operation-definition.md#tabbatchentityerror) - -5.2.18 UpdateResult [123](10-tabapi-operation-definition.md#tabupdateresult) - -5.2.19 NotUpdatedDetails [123](10-tabapi-operation-definition.md#tabnotupdateddetails) - -5.2.20 EntityTemporal [123](10-tabapi-operation-definition.md#tabentitytemporal) - -5.2.21 TemporalQuery [123](10-tabapi-operation-definition.md#tabtemporalquery) - -5.2.22 KeyValuePair [124](10-tabapi-operation-definition.md#tabkeyvaluepair) - -5.2.23 Query [125](10-tabapi-operation-definition.md#tabquery) - -5.2.24 EntityTypeList [127](10-tabapi-operation-definition.md#tabentitytypelist) - -5.2.25 EntityType [127](10-tabapi-operation-definition.md#tabentitytype) - -5.2.26 EntityTypeInfo [127](10-tabapi-operation-definition.md#tabentitytypeinfo) - -5.2.27 AttributeList [128](10-tabapi-operation-definition.md#tabattributelist) - -5.2.28 Attribute [128](10-tabapi-operation-definition.md#tabattribute) - -5.2.29 Feature [129](10-tabapi-operation-definition.md#tabfeature) - -5.2.30 FeatureCollection [129](10-tabapi-operation-definition.md#tabfeaturecollection) - -5.2.31 FeatureProperties [130](10-tabapi-operation-definition.md#tabfeatureproperties) - -5.2.32 LanguageProperty [130](10-tabapi-operation-definition.md#tablanguageproperty) - -5.2.33 EntitySelector [132](10-tabapi-operation-definition.md#tabentityselector) - -5.2.34 RegistrationManagementInfo [133](10-tabapi-operation-definition.md#tabregistrationmanagementinfo) - -5.2.35 VocabProperty [133](10-tabapi-operation-definition.md#tabvocabproperty) - -5.2.36 ListProperty [135](10-tabapi-operation-definition.md#tablistproperty) - -5.2.37 ListRelationship [137](10-tabapi-operation-definition.md#tablistrelationship) - -5.2.38 JsonProperty [139](10-tabapi-operation-definition.md#tabjsonproperty) - -5.2.39 EntityMap [141](10-tabapi-operation-definition.md#tabentitymap) - -5.2.40 Context Source Identity [142](10-tabapi-operation-definition.md#tabcontext-source-identity) - -5.2.41 Snapshot [142](10-tabapi-operation-definition.md#tabsnapshot) - -5.2.42 ExecutionResultDetails [144](10-tabapi-operation-definition.md#tabexecutionresultdetails) - -5.2.43 OrderingParams [145](10-tabapi-operation-definition.md#taborderingparams) - -5.2.44 AggregationParams [145](10-tabapi-operation-definition.md#tabaggregationparams) - -5.3 Notification data types [146](10-tabapi-operation-definition.md#tabnotification-data-types) - -5.3.1 Notification [146](10-tabapi-operation-definition.md#tabnotification) - -5.3.2 CSourceNotification [146](10-tabapi-operation-definition.md#tabcsourcenotification) - -5.3.3 TriggerReasonEnumeration [147](10-tabapi-operation-definition.md#tabtriggerreasonenumeration) - -5.3.4 SnapshotNotification [147](10-tabapi-operation-definition.md#tabsnapshotnotification) - -5.4 NGSI-LD Fragments [148](10-tabapi-operation-definition.md#tabngsi-ld-fragments) - -5.5 Common Behaviours [149](10-tabapi-operation-definition.md#tabcommon-behaviours) - -5.5.1 Introduction [149](10-tabapi-operation-definition.md#tabintroduction-17) - -5.5.2 Error types [149](10-tabapi-operation-definition.md#taberror-types) - -5.5.3 Error response payload body [150](10-tabapi-operation-definition.md#taberror-response-payload-body) - -5.5.4 General NGSI-LD validation [150](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) - -5.5.5 Default \@context assignment [151](10-tabapi-operation-definition.md#tabdefault-context-assignment) - -5.5.6 Operation execution and generic error handling [151](10-tabapi-operation-definition.md#taboperation-execution-and-generic-error-handling) - -5.5.7 Term to URI expansion or compaction [151](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) - -5.5.8 Partial Update Patch Behaviour [152](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) - -5.5.9 Pagination Behaviour [154](10-tabapi-operation-definition.md#tabpagination-behaviour) - -5.5.9.1 General Pagination Behaviour [154](10-tabapi-operation-definition.md#tabgeneral-pagination-behaviour) - -5.5.9.2 Pagination option using limit and offset [155](10-tabapi-operation-definition.md#tabpagination-option-using-limit-and-offset) - -5.5.9.3 Pagination with Entity maps [155](10-tabapi-operation-definition.md#tabpagination-with-entity-maps) - -5.5.10 Multi-Tenant Behaviour [155](10-tabapi-operation-definition.md#tabmulti-tenant-behaviour) - -5.5.11 More than one instance of the same Entity in an Entity array [156](10-tabapi-operation-definition.md#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array) - -5.5.11.0 Foreword [156](10-tabapi-operation-definition.md#tabforeword-3) - -5.5.11.1 Batch Entity Creation case [156](10-tabapi-operation-definition.md#tabbatch-entity-creation-case) - -5.5.11.2 Batch Entity Creation or Update (Upsert) case [156](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert-case) - -5.5.11.3 Batch Entity Update case [156](10-tabapi-operation-definition.md#tabbatch-entity-update-case) - -5.5.11.4 Batch Entity Delete case [156](10-tabapi-operation-definition.md#tabbatch-entity-delete-case) - -5.5.11.5 Batch Entity Merge case [157](10-tabapi-operation-definition.md#tabbatch-entity-merge-case) - -5.5.12 Merge Patch Behaviour [157](10-tabapi-operation-definition.md#tabmerge-patch-behaviour) - -5.5.13 Limiting operations to local scope [158](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope) - -5.5.14 Distributed Transactional Behaviour [159](10-tabapi-operation-definition.md#tabdistributed-transactional-behaviour) - -5.5.15 Snapshot Behaviour [159](10-tabapi-operation-definition.md#tabsnapshot-behaviour) - -5.6 Context Information Provision [159](10-tabapi-operation-definition.md#tabcontext-information-provision) - -5.6.1 Create Entity [159](10-tabapi-operation-definition.md#tabcreate-entity) - -5.6.1.1 Description [159](10-tabapi-operation-definition.md#tabdescription) - -5.6.1.2 Use case diagram [160](10-tabapi-operation-definition.md#tabuse-case-diagram) - -5.6.1.3 Input data [160](10-tabapi-operation-definition.md#tabinput-data) - -5.6.1.4 Behaviour [160](10-tabapi-operation-definition.md#tabbehaviour) - -5.6.1.5 Output data [161](10-tabapi-operation-definition.md#taboutput-data) - -5.6.2 Update Attributes [161](10-tabapi-operation-definition.md#tabupdate-attributes) - -5.6.2.1 Description [161](10-tabapi-operation-definition.md#tabdescription-1) - -5.6.2.2 Use case diagram [161](10-tabapi-operation-definition.md#tabuse-case-diagram-1) - -5.6.2.3 Input data [161](10-tabapi-operation-definition.md#tabinput-data-1) - -5.6.2.4 Behaviour [161](10-tabapi-operation-definition.md#tabbehaviour-1) - -5.6.2.5 Output data [162](10-tabapi-operation-definition.md#taboutput-data-1) - -5.6.3 Append Attributes [163](10-tabapi-operation-definition.md#tabappend-attributes) - -5.6.3.1 Description [163](10-tabapi-operation-definition.md#tabdescription-2) - -5.6.3.2 Use case diagram [163](10-tabapi-operation-definition.md#tabuse-case-diagram-2) - -5.6.3.3 Input data [163](10-tabapi-operation-definition.md#tabinput-data-2) - -5.6.3.4 Behaviour [163](10-tabapi-operation-definition.md#tabbehaviour-2) - -5.6.3.5 Output data [164](10-tabapi-operation-definition.md#taboutput-data-2) - -5.6.4 Partial Attribute update [164](10-tabapi-operation-definition.md#tabpartial-attribute-update) - -5.6.4.1 Description [164](10-tabapi-operation-definition.md#tabdescription-3) - -5.6.4.2 Use case diagram [165](10-tabapi-operation-definition.md#tabuse-case-diagram-3) - -5.6.4.3 Input data [165](10-tabapi-operation-definition.md#tabinput-data-3) - -5.6.4.4 Behaviour [165](10-tabapi-operation-definition.md#tabbehaviour-3) - -5.6.4.5 Output data [166](10-tabapi-operation-definition.md#taboutput-data-3) - -5.6.5 Delete Attribute [166](10-tabapi-operation-definition.md#tabdelete-attribute) - -5.6.5.1 Description [166](10-tabapi-operation-definition.md#tabdescription-4) - -5.6.5.2 Use case diagram [166](10-tabapi-operation-definition.md#tabuse-case-diagram-4) - -5.6.5.3 Input data [167](10-tabapi-operation-definition.md#tabinput-data-4) - -5.6.5.4 Behaviour [167](10-tabapi-operation-definition.md#tabbehaviour-4) - -5.6.5.5 Output data [167](10-tabapi-operation-definition.md#taboutput-data-4) - -5.6.6 Delete Entity [168](10-tabapi-operation-definition.md#tabdelete-entity) - -5.6.6.1 Description [168](10-tabapi-operation-definition.md#tabdescription-5) - -5.6.6.2 Use case diagram [168](10-tabapi-operation-definition.md#tabuse-case-diagram-5) - -5.6.6.3 Input data [168](10-tabapi-operation-definition.md#tabinput-data-5) - -5.6.6.4 Behaviour [168](10-tabapi-operation-definition.md#tabbehaviour-5) - -5.6.6.5 Output data [169](10-tabapi-operation-definition.md#taboutput-data-5) - -5.6.7 Batch Entity Creation [169](10-tabapi-operation-definition.md#tabbatch-entity-creation) - -5.6.7.1 Description [169](10-tabapi-operation-definition.md#tabdescription-6) - -5.6.7.2 Use case diagram [169](10-tabapi-operation-definition.md#tabuse-case-diagram-6) - -5.6.7.3 Input data [169](10-tabapi-operation-definition.md#tabinput-data-6) - -5.6.7.4 Behaviour [169](10-tabapi-operation-definition.md#tabbehaviour-6) - -5.6.7.5 Output data [170](10-tabapi-operation-definition.md#taboutput-data-6) - -5.6.8 Batch Entity Creation or Update (Upsert) [170](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert) - -5.6.8.1 Description [170](10-tabapi-operation-definition.md#tabdescription-7) - -5.6.8.2 Use case diagram [170](10-tabapi-operation-definition.md#tabuse-case-diagram-7) - -5.6.8.3 Input data [171](10-tabapi-operation-definition.md#tabinput-data-7) - -5.6.8.4 Behaviour [171](10-tabapi-operation-definition.md#tabbehaviour-7) - -5.6.8.5 Output data [173](10-tabapi-operation-definition.md#taboutput-data-7) - -5.6.9 Batch Entity Update [173](10-tabapi-operation-definition.md#tabbatch-entity-update) - -5.6.9.1 Description [173](10-tabapi-operation-definition.md#tabdescription-8) - -5.6.9.2 Use case diagram [173](10-tabapi-operation-definition.md#tabuse-case-diagram-8) - -5.6.9.3 Input data [173](10-tabapi-operation-definition.md#tabinput-data-8) - -5.6.9.4 Behaviour [173](10-tabapi-operation-definition.md#tabbehaviour-8) - -5.6.9.5 Output data [175](10-tabapi-operation-definition.md#taboutput-data-8) - -5.6.10 Batch Entity Delete [175](10-tabapi-operation-definition.md#tabbatch-entity-delete) - -5.6.10.1 Description [175](10-tabapi-operation-definition.md#tabdescription-9) - -5.6.10.2 Use case diagram [175](10-tabapi-operation-definition.md#tabuse-case-diagram-9) - -5.6.10.3 Input data [175](10-tabapi-operation-definition.md#tabinput-data-9) - -5.6.10.4 Behaviour [175](10-tabapi-operation-definition.md#tabbehaviour-9) - -5.6.10.5 Output data [176](10-tabapi-operation-definition.md#taboutput-data-9) - -5.6.11 Create or Update (Upsert) Temporal Evolution of an Entity [176](10-tabapi-operation-definition.md#tabcreate-or-update-upsert-temporal-evolution-of-an-entity) - -5.6.11.1 Description [176](10-tabapi-operation-definition.md#tabdescription-10) - -5.6.11.2 Use case diagram [176](10-tabapi-operation-definition.md#tabuse-case-diagram-10) - -5.6.11.3 Input data [177](10-tabapi-operation-definition.md#tabinput-data-10) - -5.6.11.4 Behaviour [177](10-tabapi-operation-definition.md#tabbehaviour-10) - -5.6.11.5 Output data [178](10-tabapi-operation-definition.md#taboutput-data-10) - -5.6.12 Add Attributes to Temporal Evolution of an Entity [178](10-tabapi-operation-definition.md#tabadd-attributes-to-temporal-evolution-of-an-entity) - -5.6.12.1 Description [178](10-tabapi-operation-definition.md#tabdescription-11) - -5.6.12.2 Use case diagram [178](10-tabapi-operation-definition.md#tabuse-case-diagram-11) - -5.6.12.3 Input data [178](10-tabapi-operation-definition.md#tabinput-data-11) - -5.6.12.4 Behaviour [178](10-tabapi-operation-definition.md#tabbehaviour-11) - -5.6.12.5 Output data [179](10-tabapi-operation-definition.md#taboutput-data-11) - -5.6.13 Delete Attribute from Temporal Evolution of an Entity [179](10-tabapi-operation-definition.md#tabdelete-attribute-from-temporal-evolution-of-an-entity) - -5.6.13.1 Description [179](10-tabapi-operation-definition.md#tabdescription-12) - -5.6.13.2 Use case diagram [179](10-tabapi-operation-definition.md#tabuse-case-diagram-12) - -5.6.13.3 Input data [180](10-tabapi-operation-definition.md#tabinput-data-12) - -5.6.13.4 Behaviour [180](10-tabapi-operation-definition.md#tabbehaviour-12) - -5.6.13.5 Output data [181](10-tabapi-operation-definition.md#taboutput-data-12) - -5.6.14 Modify Attribute instance in Temporal Evolution of an Entity [181](10-tabapi-operation-definition.md#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity) - -5.6.14.1 Description [181](10-tabapi-operation-definition.md#tabdescription-13) - -5.6.14.2 Use case diagram [181](10-tabapi-operation-definition.md#tabuse-case-diagram-13) - -5.6.14.3 Input data [181](10-tabapi-operation-definition.md#tabinput-data-13) - -5.6.14.4 Behaviour [182](10-tabapi-operation-definition.md#tabbehaviour-13) - -5.6.14.5 Output data [182](10-tabapi-operation-definition.md#taboutput-data-13) - -5.6.15 Delete Attribute instance from Temporal Evolution of an Entity [182](10-tabapi-operation-definition.md#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity) - -5.6.15.1 Description [182](10-tabapi-operation-definition.md#tabdescription-14) - -5.6.15.2 Use case diagram [183](10-tabapi-operation-definition.md#tabuse-case-diagram-14) - -5.6.15.3 Input data [183](10-tabapi-operation-definition.md#tabinput-data-14) - -5.6.15.4 Behaviour [183](10-tabapi-operation-definition.md#tabbehaviour-14) - -5.6.15.5 Output data [184](10-tabapi-operation-definition.md#taboutput-data-14) - -5.6.16 Delete Temporal Evolution of an Entity [184](10-tabapi-operation-definition.md#tabdelete-temporal-evolution-of-an-entity) - -5.6.16.1 Description [184](10-tabapi-operation-definition.md#tabdescription-15) - -5.6.16.2 Use case diagram [184](10-tabapi-operation-definition.md#tabuse-case-diagram-15) - -5.6.16.3 Input data [184](10-tabapi-operation-definition.md#tabinput-data-15) - -5.6.16.4 Behaviour [185](10-tabapi-operation-definition.md#tabbehaviour-15) - -5.6.16.5 Output data [185](10-tabapi-operation-definition.md#taboutput-data-15) - -5.6.17 Merge Entity [185](10-tabapi-operation-definition.md#tabmerge-entity) - -5.6.17.1 Description [185](10-tabapi-operation-definition.md#tabdescription-16) - -5.6.17.2 Use case diagram [185](10-tabapi-operation-definition.md#tabuse-case-diagram-16) - -5.6.17.3 Input data [186](10-tabapi-operation-definition.md#tabinput-data-16) - -5.6.17.4 Behaviour [186](10-tabapi-operation-definition.md#tabbehaviour-16) - -5.6.17.5 Output data [188](10-tabapi-operation-definition.md#taboutput-data-16) - -5.6.18 Replace Entity [188](10-tabapi-operation-definition.md#tabreplace-entity) - -5.6.18.1 Description [188](10-tabapi-operation-definition.md#tabdescription-17) - -5.6.18.2 Use case diagram [188](10-tabapi-operation-definition.md#tabuse-case-diagram-17) - -5.6.18.3 Input data [188](10-tabapi-operation-definition.md#tabinput-data-17) - -5.6.18.4 Behaviour [188](10-tabapi-operation-definition.md#tabbehaviour-17) - -5.6.18.5 Output data [189](10-tabapi-operation-definition.md#taboutput-data-17) - -5.6.19 Replace Attribute [189](10-tabapi-operation-definition.md#tabreplace-attribute) - -5.6.19.1 Description [189](10-tabapi-operation-definition.md#tabdescription-18) - -5.6.19.2 Use case diagram [189](10-tabapi-operation-definition.md#tabuse-case-diagram-18) - -5.6.19.3 Input data [190](10-tabapi-operation-definition.md#tabinput-data-18) - -5.6.19.4 Behaviour [190](10-tabapi-operation-definition.md#tabbehaviour-18) - -5.6.19.5 Output data [190](10-tabapi-operation-definition.md#taboutput-data-18) - -5.6.20 Batch Entity Merge [191](10-tabapi-operation-definition.md#tabbatch-entity-merge) - -5.6.20.1 Description [191](10-tabapi-operation-definition.md#tabdescription-19) - -5.6.20.2 Use case diagram [191](10-tabapi-operation-definition.md#tabuse-case-diagram-19) - -5.6.20.3 Input data [191](10-tabapi-operation-definition.md#tabinput-data-19) - -5.6.20.4 Behaviour [191](10-tabapi-operation-definition.md#tabbehaviour-19) - -5.6.20.5 Output data [192](10-tabapi-operation-definition.md#taboutput-data-19) - -5.6.21 Purge Entities [192](10-tabapi-operation-definition.md#tabpurge-entities) - -5.6.21.1 Description [192](10-tabapi-operation-definition.md#tabdescription-20) - -5.6.21.2 Use case diagram [192](10-tabapi-operation-definition.md#tabuse-case-diagram-20) - -5.6.21.3 Input data [193](10-tabapi-operation-definition.md#tabinput-data-20) - -5.6.21.4 Behaviour [193](10-tabapi-operation-definition.md#tabbehaviour-20) - -5.6.21.5 Output data [194](10-tabapi-operation-definition.md#taboutput-data-20) - -5.7 Context Information Consumption [195](10-tabapi-operation-definition.md#tabcontext-information-consumption) - -5.7.1 Retrieve Entity [195](10-tabapi-operation-definition.md#tabretrieve-entity) - -5.7.1.1 Description [195](10-tabapi-operation-definition.md#tabdescription-21) - -5.7.1.2 Use case diagram [195](10-tabapi-operation-definition.md#tabuse-case-diagram-21) - -5.7.1.3 Input data [195](10-tabapi-operation-definition.md#tabinput-data-21) - -5.7.1.4 Behaviour [196](10-tabapi-operation-definition.md#tabbehaviour-21) - -5.7.1.5 Output data [197](10-tabapi-operation-definition.md#taboutput-data-21) - -5.7.2 Query Entities [198](10-tabapi-operation-definition.md#tabquery-entities) - -5.7.2.1 Description [198](10-tabapi-operation-definition.md#tabdescription-22) - -5.7.2.2 Use case diagram [198](10-tabapi-operation-definition.md#tabuse-case-diagram-22) - -5.7.2.3 Input data [198](10-tabapi-operation-definition.md#tabinput-data-22) - -5.7.2.4 Behaviour [200](10-tabapi-operation-definition.md#tabbehaviour-22) - -5.7.2.5 Output data [202](10-tabapi-operation-definition.md#taboutput-data-22) - -5.7.3 Retrieve Temporal Evolution of an Entity [203](10-tabapi-operation-definition.md#tabretrieve-temporal-evolution-of-an-entity) - -5.7.3.1 Description [203](10-tabapi-operation-definition.md#tabdescription-23) - -5.7.3.2 Use case diagram [203](10-tabapi-operation-definition.md#tabuse-case-diagram-23) - -5.7.3.3 Input data [203](10-tabapi-operation-definition.md#tabinput-data-23) - -5.7.3.4 Behaviour [204](10-tabapi-operation-definition.md#tabbehaviour-23) - -5.7.3.5 Output data [205](10-tabapi-operation-definition.md#taboutput-data-23) - -5.7.4 Query Temporal Evolution of Entities [205](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities) - -5.7.4.1 Description [205](10-tabapi-operation-definition.md#tabdescription-24) - -5.7.4.2 Use case diagram [205](10-tabapi-operation-definition.md#tabuse-case-diagram-24) - -5.7.4.3 Input data [206](10-tabapi-operation-definition.md#tabinput-data-24) - -5.7.4.4 Behaviour [207](10-tabapi-operation-definition.md#tabbehaviour-24) - -5.7.4.5 Output Data [210](10-tabapi-operation-definition.md#taboutput-data-24) - -5.7.5 Retrieve Available Entity Types [210](10-tabapi-operation-definition.md#tabretrieve-available-entity-types) - -5.7.5.1 Description [210](10-tabapi-operation-definition.md#tabdescription-25) - -5.7.5.2 Use case diagram [210](10-tabapi-operation-definition.md#tabuse-case-diagram-25) - -5.7.5.3 Input data [211](10-tabapi-operation-definition.md#tabinput-data-25) - -5.7.5.4 Behaviour [211](10-tabapi-operation-definition.md#tabbehaviour-25) - -5.7.5.5 Output data [211](10-tabapi-operation-definition.md#taboutput-data-25) - -5.7.6 Retrieve Details of Available Entity Types [211](10-tabapi-operation-definition.md#tabretrieve-details-of-available-entity-types) - -5.7.6.1 Description [211](10-tabapi-operation-definition.md#tabdescription-26) - -5.7.6.2 Use case diagram [211](10-tabapi-operation-definition.md#tabuse-case-diagram-26) - -5.7.6.3 Input data [211](10-tabapi-operation-definition.md#tabinput-data-26) - -5.7.6.4 Behaviour [211](10-tabapi-operation-definition.md#tabbehaviour-26) - -5.7.6.5 Output data [212](10-tabapi-operation-definition.md#taboutput-data-26) - -5.7.7 Retrieve Available Entity Type Information [212](10-tabapi-operation-definition.md#tabretrieve-available-entity-type-information) - -5.7.7.1 Description [212](10-tabapi-operation-definition.md#tabdescription-27) - -5.7.7.2 Use case diagram [212](10-tabapi-operation-definition.md#tabuse-case-diagram-27) - -5.7.7.3 Input data [212](10-tabapi-operation-definition.md#tabinput-data-27) - -5.7.7.4 Behaviour [212](10-tabapi-operation-definition.md#tabbehaviour-27) - -5.7.7.5 Output data [212](10-tabapi-operation-definition.md#taboutput-data-27) - -5.7.8 Retrieve Available Attributes [213](10-tabapi-operation-definition.md#tabretrieve-available-attributes) - -5.7.8.1 Description [213](10-tabapi-operation-definition.md#tabdescription-28) - -5.7.8.2 Use case diagram [213](10-tabapi-operation-definition.md#tabuse-case-diagram-28) - -5.7.8.3 Input data [213](10-tabapi-operation-definition.md#tabinput-data-28) - -5.7.8.4 Behaviour [213](10-tabapi-operation-definition.md#tabbehaviour-28) - -5.7.8.5 Output data [213](10-tabapi-operation-definition.md#taboutput-data-28) - -5.7.9 Retrieve Details of Available Attributes [213](10-tabapi-operation-definition.md#tabretrieve-details-of-available-attributes) - -5.7.9.1 Description [213](10-tabapi-operation-definition.md#tabdescription-29) - -5.7.9.2 Use case diagram [214](10-tabapi-operation-definition.md#tabuse-case-diagram-29) - -5.7.9.3 Input data [214](10-tabapi-operation-definition.md#tabinput-data-29) - -5.7.9.4 Behaviour [214](10-tabapi-operation-definition.md#tabbehaviour-29) - -5.7.9.5 Output data [214](10-tabapi-operation-definition.md#taboutput-data-29) - -5.7.10 Retrieve Available Attribute Information [214](10-tabapi-operation-definition.md#tabretrieve-available-attribute-information) - -5.7.10.1 Description [214](10-tabapi-operation-definition.md#tabdescription-30) - -5.7.10.2 Use case diagram [214](10-tabapi-operation-definition.md#tabuse-case-diagram-30) - -5.7.10.3 Input data [215](10-tabapi-operation-definition.md#tabinput-data-30) - -5.7.10.4 Behaviour [215](10-tabapi-operation-definition.md#tabbehaviour-30) - -5.7.10.5 Output data [215](10-tabapi-operation-definition.md#taboutput-data-30) - -5.7.11 Architecture-related aspects of retrieval of Entity Types and Attributes [215](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) - -5.8 Context Information Subscription [216](10-tabapi-operation-definition.md#tabcontext-information-subscription) - -5.8.1 Create Subscription [216](10-tabapi-operation-definition.md#tabcreate-subscription) - -5.8.1.1 Description [216](10-tabapi-operation-definition.md#tabdescription-31) - -5.8.1.2 Use case diagram [216](10-tabapi-operation-definition.md#tabuse-case-diagram-31) - -5.8.1.3 Input data [216](10-tabapi-operation-definition.md#tabinput-data-31) - -5.8.1.4 Behaviour [216](10-tabapi-operation-definition.md#tabbehaviour-31) - -5.8.1.5 Output data [218](10-tabapi-operation-definition.md#taboutput-data-31) - -5.8.2 Update Subscription [218](10-tabapi-operation-definition.md#tabupdate-subscription) - -5.8.2.1 Description [218](10-tabapi-operation-definition.md#tabdescription-32) - -5.8.2.2 Use case diagram [218](10-tabapi-operation-definition.md#tabuse-case-diagram-32) - -5.8.2.3 Input data [218](10-tabapi-operation-definition.md#tabinput-data-32) - -5.8.2.4 Behaviour [219](10-tabapi-operation-definition.md#tabbehaviour-32) - -5.8.2.5 Output data [219](10-tabapi-operation-definition.md#taboutput-data-32) - -5.8.3 Retrieve Subscription [219](10-tabapi-operation-definition.md#tabretrieve-subscription) - -5.8.3.1 Description [219](10-tabapi-operation-definition.md#tabdescription-33) - -5.8.3.2 Use case diagram [219](10-tabapi-operation-definition.md#tabuse-case-diagram-33) - -5.8.3.3 Input data [220](10-tabapi-operation-definition.md#tabinput-data-33) - -5.8.3.4 Behaviour [220](10-tabapi-operation-definition.md#tabbehaviour-33) - -5.8.3.5 Output data [220](10-tabapi-operation-definition.md#taboutput-data-33) - -5.8.4 Query Subscriptions [220](10-tabapi-operation-definition.md#tabquery-subscriptions) - -5.8.4.1 Description [220](10-tabapi-operation-definition.md#tabdescription-34) - -5.8.4.2 Use case diagram [220](10-tabapi-operation-definition.md#tabuse-case-diagram-34) - -5.8.4.3 Input data [221](10-tabapi-operation-definition.md#tabinput-data-34) - -5.8.4.4 Behaviour [221](10-tabapi-operation-definition.md#tabbehaviour-34) - -5.8.4.5 Output data [221](10-tabapi-operation-definition.md#taboutput-data-34) - -5.8.5 Delete Subscription [221](10-tabapi-operation-definition.md#tabdelete-subscription) - -5.8.5.1 Description [221](10-tabapi-operation-definition.md#tabdescription-35) - -5.8.5.2 Use case diagram [221](10-tabapi-operation-definition.md#tabuse-case-diagram-35) - -5.8.5.3 Input data [222](10-tabapi-operation-definition.md#tabinput-data-35) - -5.8.5.4 Behaviour [222](10-tabapi-operation-definition.md#tabbehaviour-35) - -5.8.5.5 Output data [222](10-tabapi-operation-definition.md#taboutput-data-35) - -5.8.6 Notification behaviour [222](10-tabapi-operation-definition.md#tabnotification-behaviour) - -5.9 Context Source Registration [224](10-tabapi-operation-definition.md#tabcontext-source-registration) - -5.9.1 Introduction [224](10-tabapi-operation-definition.md#tabintroduction-18) - -5.9.2 Register Context Source [224](10-tabapi-operation-definition.md#tabregister-context-source) - -5.9.2.1 Description [224](10-tabapi-operation-definition.md#tabdescription-36) - -5.9.2.2 Use case diagram [225](10-tabapi-operation-definition.md#tabuse-case-diagram-36) - -5.9.2.3 Input data [225](10-tabapi-operation-definition.md#tabinput-data-36) - -5.9.2.4 Behaviour [225](10-tabapi-operation-definition.md#tabbehaviour-36) - -5.9.2.5 Output data [226](10-tabapi-operation-definition.md#taboutput-data-36) - -5.9.3 Update Context Source Registration [226](10-tabapi-operation-definition.md#tabupdate-context-source-registration) - -5.9.3.1 Description [226](10-tabapi-operation-definition.md#tabdescription-37) - -5.9.3.2 Use case diagram [226](10-tabapi-operation-definition.md#tabuse-case-diagram-37) - -5.9.3.3 Input data [226](10-tabapi-operation-definition.md#tabinput-data-37) - -5.9.3.4 Behaviour [227](10-tabapi-operation-definition.md#tabbehaviour-37) - -5.9.3.5 Output data [227](10-tabapi-operation-definition.md#taboutput-data-37) - -5.9.4 Delete Context Source Registration [227](10-tabapi-operation-definition.md#tabdelete-context-source-registration) - -5.9.4.1 Description [227](10-tabapi-operation-definition.md#tabdescription-38) - -5.9.4.2 Use case diagram [227](10-tabapi-operation-definition.md#tabuse-case-diagram-38) - -5.9.4.3 Input data [228](10-tabapi-operation-definition.md#tabinput-data-38) - -5.9.4.4 Behaviour [228](10-tabapi-operation-definition.md#tabbehaviour-38) - -5.9.4.5 Output data [228](10-tabapi-operation-definition.md#taboutput-data-38) - -5.10 Context Source Discovery [228](10-tabapi-operation-definition.md#tabcontext-source-discovery) - -5.10.1 Retrieve Context Source Registration [228](10-tabapi-operation-definition.md#tabretrieve-context-source-registration) - -5.10.1.1 Description [228](10-tabapi-operation-definition.md#tabdescription-39) - -5.10.1.2 Use case diagram [228](10-tabapi-operation-definition.md#tabuse-case-diagram-39) - -5.10.1.3 Input data [229](10-tabapi-operation-definition.md#tabinput-data-39) - -5.10.1.4 Behaviour [229](10-tabapi-operation-definition.md#tabbehaviour-39) - -5.10.1.5 Output data [229](10-tabapi-operation-definition.md#taboutput-data-39) - -5.10.2 Query Context Source Registrations [229](10-tabapi-operation-definition.md#tabquery-context-source-registrations) - -5.10.2.1 Description [229](10-tabapi-operation-definition.md#tabdescription-40) - -5.10.2.2 Use case diagram [230](10-tabapi-operation-definition.md#tabuse-case-diagram-40) - -5.10.2.3 Input data [230](10-tabapi-operation-definition.md#tabinput-data-40) - -5.10.2.4 Behaviour [231](10-tabapi-operation-definition.md#tabbehaviour-40) - -5.10.2.5 Output data [232](10-tabapi-operation-definition.md#taboutput-data-40) - -5.11 Context Source Registration Subscription [232](10-tabapi-operation-definition.md#tabcontext-source-registration-subscription) - -5.11.1 Introduction [232](10-tabapi-operation-definition.md#tabintroduction-19) - -5.11.2 Create Context Source Registration Subscription [232](10-tabapi-operation-definition.md#tabcreate-context-source-registration-subscription) - -5.11.2.1 Description [232](10-tabapi-operation-definition.md#tabdescription-41) - -5.11.2.2 Use case diagram [232](10-tabapi-operation-definition.md#tabuse-case-diagram-41) - -5.11.2.3 Input data [232](10-tabapi-operation-definition.md#tabinput-data-41) - -5.11.2.4 Behaviour [233](10-tabapi-operation-definition.md#tabbehaviour-41) - -5.11.2.5 Output data [233](10-tabapi-operation-definition.md#taboutput-data-41) - -5.11.3 Update Context Source Registration Subscription [234](10-tabapi-operation-definition.md#tabupdate-context-source-registration-subscription) - -5.11.3.1 Description [234](10-tabapi-operation-definition.md#tabdescription-42) - -5.11.3.2 Use case diagram [234](10-tabapi-operation-definition.md#tabuse-case-diagram-42) - -5.11.3.3 Input data [234](10-tabapi-operation-definition.md#tabinput-data-42) - -5.11.3.4 Behaviour [234](10-tabapi-operation-definition.md#tabbehaviour-42) - -5.11.3.5 Output data [234](10-tabapi-operation-definition.md#taboutput-data-42) - -5.11.4 Retrieve Context Source Registration Subscription [234](10-tabapi-operation-definition.md#tabretrieve-context-source-registration-subscription) - -5.11.4.1 Description [234](10-tabapi-operation-definition.md#tabdescription-43) - -5.11.4.2 Use case diagram [235](10-tabapi-operation-definition.md#tabuse-case-diagram-43) - -5.11.4.3 Input data [235](10-tabapi-operation-definition.md#tabinput-data-43) - -5.11.4.4 Behaviour [235](10-tabapi-operation-definition.md#tabbehaviour-43) - -5.11.4.5 Output data [235](10-tabapi-operation-definition.md#taboutput-data-43) - -5.11.5 Query Context Source Registration Subscriptions [235](10-tabapi-operation-definition.md#tabquery-context-source-registration-subscriptions) - -5.11.5.1 Description [235](10-tabapi-operation-definition.md#tabdescription-44) - -5.11.5.2 Use case diagram [235](10-tabapi-operation-definition.md#tabuse-case-diagram-44) - -5.11.5.3 Input data [236](10-tabapi-operation-definition.md#tabinput-data-44) - -5.11.5.4 Behaviour [236](10-tabapi-operation-definition.md#tabbehaviour-44) - -5.11.5.5 Output data [236](10-tabapi-operation-definition.md#taboutput-data-44) - -5.11.6 Delete Context Source Registration Subscription [236](10-tabapi-operation-definition.md#tabdelete-context-source-registration-subscription) - -5.11.6.1 Description [236](10-tabapi-operation-definition.md#tabdescription-45) - -5.11.6.2 Use case diagram [236](10-tabapi-operation-definition.md#tabuse-case-diagram-45) - -5.11.6.3 Input data [237](10-tabapi-operation-definition.md#tabinput-data-45) - -5.11.6.4 Behaviour [237](10-tabapi-operation-definition.md#tabbehaviour-45) - -5.11.6.5 Output data [237](10-tabapi-operation-definition.md#taboutput-data-45) - -5.11.7 Notification behaviour [237](10-tabapi-operation-definition.md#tabnotification-behaviour-1) - -5.12 Matching Context Source Registrations [238](10-tabapi-operation-definition.md#tabmatching-context-source-registrations) - -5.13 Storing, Managing and Serving \@contexts [239](10-tabapi-operation-definition.md#tabstoring-managing-and-serving-contexts) - -5.13.1 Introduction [239](10-tabapi-operation-definition.md#tabintroduction-20) - -5.13.2 Add \@context [240](10-tabapi-operation-definition.md#tabadd-context) - -5.13.2.1 Description [240](10-tabapi-operation-definition.md#tabdescription-46) - -5.13.2.2 Use case diagram [240](10-tabapi-operation-definition.md#tabuse-case-diagram-46) - -5.13.2.3 Input data [240](10-tabapi-operation-definition.md#tabinput-data-46) - -5.13.2.4 Behaviour [241](10-tabapi-operation-definition.md#tabbehaviour-46) - -5.13.2.5 Output data [241](10-tabapi-operation-definition.md#taboutput-data-46) - -5.13.3 List \@contexts [241](10-tabapi-operation-definition.md#tablist-contexts) - -5.13.3.1 Description [241](10-tabapi-operation-definition.md#tabdescription-47) - -5.13.3.2 Use case diagram [241](10-tabapi-operation-definition.md#tabuse-case-diagram-47) - -5.13.3.3 Input data [241](10-tabapi-operation-definition.md#tabinput-data-47) - -5.13.3.4 Behaviour [242](10-tabapi-operation-definition.md#tabbehaviour-47) - -5.13.3.5 Output data [242](10-tabapi-operation-definition.md#taboutput-data-47) - -5.13.4 Serve \@context [242](10-tabapi-operation-definition.md#tabserve-context) - -5.13.4.1 Description [242](10-tabapi-operation-definition.md#tabdescription-48) - -5.13.4.2 Use case diagram [242](10-tabapi-operation-definition.md#tabuse-case-diagram-48) - -5.13.4.3 Input data [243](10-tabapi-operation-definition.md#tabinput-data-48) - -5.13.4.4 Behaviour [243](10-tabapi-operation-definition.md#tabbehaviour-48) - -5.13.4.5 Output data [243](10-tabapi-operation-definition.md#taboutput-data-48) - -5.13.5 Delete and Reload \@context [243](10-tabapi-operation-definition.md#tabdelete-and-reload-context) - -5.13.5.1 Description [243](10-tabapi-operation-definition.md#tabdescription-49) - -5.13.5.2 Use case diagram [243](10-tabapi-operation-definition.md#tabuse-case-diagram-49) - -5.13.5.3 Input data [244](10-tabapi-operation-definition.md#tabinput-data-49) - -5.13.5.4 Behaviour [244](10-tabapi-operation-definition.md#tabbehaviour-49) - -5.13.5.5 Output data [244](10-tabapi-operation-definition.md#taboutput-data-49) - -5.14 Context Source Entity Mapping [244](10-tabapi-operation-definition.md#tabcontext-source-entity-mapping) - -5.14.1 Retrieve EntityMap [244](10-tabapi-operation-definition.md#tabretrieve-entitymap) - -5.14.1.1 Description [244](10-tabapi-operation-definition.md#tabdescription-50) - -5.14.1.2 Use case diagram [244](10-tabapi-operation-definition.md#tabuse-case-diagram-50) - -5.14.1.3 Input data [245](10-tabapi-operation-definition.md#tabinput-data-50) - -5.14.1.4 Behaviour [245](10-tabapi-operation-definition.md#tabbehaviour-50) - -5.14.1.5 Output data [245](10-tabapi-operation-definition.md#taboutput-data-50) - -5.14.2 Update EntityMap [245](10-tabapi-operation-definition.md#tabupdate-entitymap) - -5.14.2.1 Description [245](10-tabapi-operation-definition.md#tabdescription-51) - -5.14.2.2 Use case diagram [245](10-tabapi-operation-definition.md#tabuse-case-diagram-51) - -5.14.2.3 Input data [246](10-tabapi-operation-definition.md#tabinput-data-51) - -5.14.2.4 Behaviour [246](10-tabapi-operation-definition.md#tabbehaviour-51) - -5.14.2.5 Output data [246](10-tabapi-operation-definition.md#taboutput-data-51) - -5.14.3 Delete EntityMap [246](10-tabapi-operation-definition.md#tabdelete-entitymap) - -5.14.3.1 Description [246](10-tabapi-operation-definition.md#tabdescription-52) - -5.14.3.2 Use case diagram [246](10-tabapi-operation-definition.md#tabuse-case-diagram-52) - -5.14.3.3 Input data [247](10-tabapi-operation-definition.md#tabinput-data-52) - -5.14.3.4 Behaviour [247](10-tabapi-operation-definition.md#tabbehaviour-52) - -5.14.3.5 Output data [247](10-tabapi-operation-definition.md#taboutput-data-52) - -5.14.4 Create EntityMap for Query Entities [247](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-entities) - -5.14.4.1 Description [247](10-tabapi-operation-definition.md#tabdescription-53) - -5.14.4.2 Use case diagram [247](10-tabapi-operation-definition.md#tabuse-case-diagram-53) - -5.14.4.3 Input data [248](10-tabapi-operation-definition.md#tabinput-data-53) - -5.14.4.4 Behaviour [249](10-tabapi-operation-definition.md#tabbehaviour-53) - -5.14.4.5 Output data [250](10-tabapi-operation-definition.md#taboutput-data-53) - -5.14.5 Create EntityMap for Query Temporal Evolution of Entities [251](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-temporal-evolution-of-entities) - -5.14.5.1 Description [251](10-tabapi-operation-definition.md#tabdescription-54) - -5.14.5.2 Use case diagram [251](10-tabapi-operation-definition.md#tabuse-case-diagram-54) - -5.14.5.3 Input data [251](10-tabapi-operation-definition.md#tabinput-data-54) - -5.14.5.4 Behaviour [252](10-tabapi-operation-definition.md#tabbehaviour-54) - -5.14.5.5 Output Data [254](10-tabapi-operation-definition.md#taboutput-data-54) - -5.15 Context Source Identity Information [254](10-tabapi-operation-definition.md#tabcontext-source-identity-information) - -5.15.1 Retrieve Context Source Identity Information [254](10-tabapi-operation-definition.md#tabretrieve-context-source-identity-information) - -5.15.1.1 Description [254](10-tabapi-operation-definition.md#tabdescription-55) - -5.15.1.2 Use case diagram [254](10-tabapi-operation-definition.md#tabuse-case-diagram-55) - -5.15.1.3 Input data [255](10-tabapi-operation-definition.md#tabinput-data-55) - -5.15.1.4 Behaviour [255](10-tabapi-operation-definition.md#tabbehaviour-55) - -5.15.1.5 Output data [255](10-tabapi-operation-definition.md#taboutput-data-55) - -5.16 Snapshot Functionality [255](10-tabapi-operation-definition.md#tabsnapshot-functionality) - -5.16.1 Create Snapshot [255](10-tabapi-operation-definition.md#tabcreate-snapshot) - -5.16.1.1 Description [255](10-tabapi-operation-definition.md#tabdescription-56) - -5.16.1.2 Use case diagram [255](10-tabapi-operation-definition.md#tabuse-case-diagram-56) - -5.16.1.3 Input data [255](10-tabapi-operation-definition.md#tabinput-data-56) - -5.16.1.4 Behaviour [256](10-tabapi-operation-definition.md#tabbehaviour-56) - -5.16.1.5 Output data [256](10-tabapi-operation-definition.md#taboutput-data-56) - -5.16.2 Clone Snapshot [256](10-tabapi-operation-definition.md#tabclone-snapshot) - -5.16.2.1 Description [256](10-tabapi-operation-definition.md#tabdescription-57) - -5.16.2.2 Use case diagram [256](10-tabapi-operation-definition.md#tabuse-case-diagram-57) - -5.16.2.3 Input data [257](10-tabapi-operation-definition.md#tabinput-data-57) - -5.16.2.4 Behaviour [257](10-tabapi-operation-definition.md#tabbehaviour-57) - -5.16.2.5 Output data [258](10-tabapi-operation-definition.md#taboutput-data-57) - -5.16.3 Retrieve Snapshot Status [258](10-tabapi-operation-definition.md#tabretrieve-snapshot-status) - -5.16.3.1 Description [258](10-tabapi-operation-definition.md#tabdescription-58) - -5.16.3.2 Use case diagram [258](10-tabapi-operation-definition.md#tabuse-case-diagram-58) - -5.16.3.3 Input data [258](10-tabapi-operation-definition.md#tabinput-data-58) - -5.16.3.4 Behaviour [258](10-tabapi-operation-definition.md#tabbehaviour-58) - -5.16.3.5 Output data [258](10-tabapi-operation-definition.md#taboutput-data-58) - -5.16.4 Update Snapshot Status [258](10-tabapi-operation-definition.md#tabupdate-snapshot-status) - -5.16.4.1 Description [258](10-tabapi-operation-definition.md#tabdescription-59) - -5.16.4.2 Use case diagram [259](10-tabapi-operation-definition.md#tabuse-case-diagram-59) - -5.16.4.3 Input data [259](10-tabapi-operation-definition.md#tabinput-data-59) - -5.16.4.4 Behaviour [259](10-tabapi-operation-definition.md#tabbehaviour-59) - -5.16.4.5 Output data [259](10-tabapi-operation-definition.md#taboutput-data-59) - -5.16.5 Delete Snapshot [259](10-tabapi-operation-definition.md#tabdelete-snapshot) - -5.16.5.1 Description [259](10-tabapi-operation-definition.md#tabdescription-60) - -5.16.5.2 Use case diagram [260](10-tabapi-operation-definition.md#tabuse-case-diagram-60) - -5.16.5.3 Input data [260](10-tabapi-operation-definition.md#tabinput-data-60) - -5.16.5.4 Behaviour [260](10-tabapi-operation-definition.md#tabbehaviour-60) - -5.16.5.5 Output data [260](10-tabapi-operation-definition.md#taboutput-data-60) - -5.16.6 Snapshot status notification behaviour [260](10-tabapi-operation-definition.md#tabsnapshot-status-notification-behaviour) - -5.16.7 Purge Snapshots [261](10-tabapi-operation-definition.md#tabpurge-snapshots) - -5.16.7.1 Description [261](10-tabapi-operation-definition.md#tabdescription-61) - -5.16.7.2 Use case diagram [261](10-tabapi-operation-definition.md#tabuse-case-diagram-61) - -5.16.7.3 Input data [261](10-tabapi-operation-definition.md#tabinput-data-61) - -5.16.7.4 Behaviour [261](10-tabapi-operation-definition.md#tabbehaviour-61) - -5.16.7.5 Output data [261](10-tabapi-operation-definition.md#taboutput-data-61) - -6 API HTTP Binding [261](11-tabapi-http-binding.md#tabapi-http-binding) - -6.1 Introduction [261](11-tabapi-http-binding.md#tabintroduction-21) - -6.2 Global Definitions and Resource Structure [262](11-tabapi-http-binding.md#tabglobal-definitions-and-resource-structure) - -6.3 Common Behaviours [267](11-tabapi-http-binding.md#tabcommon-behaviours-1) - -6.3.1 Introduction [267](11-tabapi-http-binding.md#tabintroduction-22) - -6.3.2 Error Types [267](11-tabapi-http-binding.md#taberror-types-1) - -6.3.3 Reporting errors [267](11-tabapi-http-binding.md#tabreporting-errors) - -6.3.4 HTTP request preconditions [267](11-tabapi-http-binding.md#tabhttp-request-preconditions) - -6.3.5 JSON-LD \@context resolution [268](11-tabapi-http-binding.md#tabjson-ld-context-resolution) - -6.3.6 HTTP response common requirements [269](11-tabapi-http-binding.md#tabhttp-response-common-requirements) - -6.3.7 Representation of Entities [269](11-tabapi-http-binding.md#tabrepresentation-of-entities) - -6.3.8 Notification behaviour [270](11-tabapi-http-binding.md#tabnotification-behaviour-2) - -6.3.9 Csource Notification behaviour [271](11-tabapi-http-binding.md#tabcsource-notification-behaviour) - -6.3.10 Pagination behaviour [271](11-tabapi-http-binding.md#tabpagination-behaviour-1) - -6.3.11 Including system Attributes [273](11-tabapi-http-binding.md#tabincluding-system-attributes) - -6.3.12 Simplified or aggregated temporal representation of Entities [273](11-tabapi-http-binding.md#tabsimplified-or-aggregated-temporal-representation-of-entities) - -6.3.13 Counting number of results [274](11-tabapi-http-binding.md#tabcounting-number-of-results) - -6.3.14 Tenant specification [274](11-tabapi-http-binding.md#tabtenant-specification) - -6.3.15 GeoJSON representation of spatially bound entities [275](11-tabapi-http-binding.md#tabgeojson-representation-of-spatially-bound-entities) - -6.3.16 Expiration time for cached \@contexts [275](11-tabapi-http-binding.md#tabexpiration-time-for-cached-contexts) - -6.3.17 Distributed Operations Caching and Timeout Behaviour [275](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour) - -6.3.18 Limiting Distributed Operations [276](11-tabapi-http-binding.md#tablimiting-distributed-operations) - -6.3.19 Extra information to provide when contacting Context Source [276](11-tabapi-http-binding.md#tabextra-information-to-provide-when-contacting-context-source-1) - -6.3.20 Invalid parameters [277](11-tabapi-http-binding.md#tabinvalid-parameters) - -6.3.21 Optional profile information regarding versioning and datatype conformance [277](11-tabapi-http-binding.md#taboptional-profile-information-regarding-versioning-and-datatype-conformance) - -6.3.22 Snapshot specification [277](11-tabapi-http-binding.md#tabsnapshot-specification) - -6.4 Resource: entities/ [277](11-tabapi-http-binding.md#tabresource-entities) - -6.4.1 Description [277](11-tabapi-http-binding.md#tabdescription-62) - -6.4.2 Resource definition [277](11-tabapi-http-binding.md#tabresource-definition) - -6.4.3 Resource methods [277](11-tabapi-http-binding.md#tabresource-methods) - -6.4.3.1 POST [277](11-tabapi-http-binding.md#tabpost) - -6.4.3.2 GET [279](11-tabapi-http-binding.md#tabget) - -6.4.3.3 DELETE [283](11-tabapi-http-binding.md#tabdelete) - -6.5 Resource: entities/{entityId} [285](11-tabapi-http-binding.md#tabresource-entitiesentityid) - -6.5.1 Description [285](11-tabapi-http-binding.md#tabdescription-63) - -6.5.2 Resource definition [286](11-tabapi-http-binding.md#tabresource-definition-1) - -6.5.3 Resource methods [286](11-tabapi-http-binding.md#tabresource-methods-1) - -6.5.3.1 GET [286](11-tabapi-http-binding.md#tabget-1) - -6.5.3.2 DELETE [288](11-tabapi-http-binding.md#tabdelete-1) - -6.5.3.3 PUT [289](11-tabapi-http-binding.md#tabput) - -6.5.3.4 PATCH [291](11-tabapi-http-binding.md#tabpatch) - -6.6 Resource: entities/{entityId}/attrs/ [292](11-tabapi-http-binding.md#tabresource-entitiesentityidattrs) - -6.6.1 Description [292](11-tabapi-http-binding.md#tabdescription-64) - -6.6.2 Resource definition [292](11-tabapi-http-binding.md#tabresource-definition-2) - -6.6.3 Resource methods [293](11-tabapi-http-binding.md#tabresource-methods-2) - -6.6.3.1 POST [293](11-tabapi-http-binding.md#tabpost-1) - -6.6.3.2 PATCH [294](11-tabapi-http-binding.md#tabpatch-1) - -6.7 Resource: entities/{entityId}/attrs/{attrId} [295](11-tabapi-http-binding.md#tabresource-entitiesentityidattrsattrid) - -6.7.1 Description [295](11-tabapi-http-binding.md#tabdescription-65) - -6.7.2 Resource definition [295](11-tabapi-http-binding.md#tabresource-definition-3) - -6.7.3 Resource methods [296](11-tabapi-http-binding.md#tabresource-methods-3) - -6.7.3.1 PATCH [296](11-tabapi-http-binding.md#tabpatch-2) - -6.7.3.2 DELETE [297](11-tabapi-http-binding.md#tabdelete-2) - -6.7.3.3 PUT [298](11-tabapi-http-binding.md#tabput-1) - -6.8 Resource: csourceRegistrations/ [300](11-tabapi-http-binding.md#tabresource-csourceregistrations) - -6.8.1 Description [300](11-tabapi-http-binding.md#tabdescription-66) - -6.8.2 Resource definition [300](11-tabapi-http-binding.md#tabresource-definition-4) - -6.8.3 Resource methods [300](11-tabapi-http-binding.md#tabresource-methods-4) - -6.8.3.1 POST [300](11-tabapi-http-binding.md#tabpost-2) - -6.8.3.2 GET [301](11-tabapi-http-binding.md#tabget-2) - -6.9 Resource: csourceRegistrations/{registrationId} [303](11-tabapi-http-binding.md#tabresource-csourceregistrationsregistrationid) - -6.9.1 Description [303](11-tabapi-http-binding.md#tabdescription-67) - -6.9.2 Resource definition [303](11-tabapi-http-binding.md#tabresource-definition-5) - -6.9.3 Resource methods [304](11-tabapi-http-binding.md#tabresource-methods-5) - -6.9.3.1 GET [304](11-tabapi-http-binding.md#tabget-3) - -6.9.3.2 PATCH [304](11-tabapi-http-binding.md#tabpatch-3) - -6.9.3.3 DELETE [305](11-tabapi-http-binding.md#tabdelete-3) - -6.10 Resource: subscriptions/ [306](11-tabapi-http-binding.md#tabresource-subscriptions) - -6.10.1 Description [306](11-tabapi-http-binding.md#tabdescription-68) - -6.10.2 Resource definition [306](11-tabapi-http-binding.md#tabresource-definition-6) - -6.10.3 Resource methods [306](11-tabapi-http-binding.md#tabresource-methods-6) - -6.10.3.1 POST [306](11-tabapi-http-binding.md#tabpost-3) - -6.10.3.2 GET [307](11-tabapi-http-binding.md#tabget-4) - -6.11 Resource: subscriptions/{subscriptionId} [308](11-tabapi-http-binding.md#tabresource-subscriptionssubscriptionid) - -6.11.1 Description [308](11-tabapi-http-binding.md#tabdescription-69) - -6.11.2 Resource definition [308](11-tabapi-http-binding.md#tabresource-definition-7) - -6.11.3 Resource methods [308](11-tabapi-http-binding.md#tabresource-methods-7) - -6.11.3.1 GET [308](11-tabapi-http-binding.md#tabget-5) - -6.11.3.2 PATCH [309](11-tabapi-http-binding.md#tabpatch-4) - -6.11.3.3 DELETE [309](11-tabapi-http-binding.md#tabdelete-4) - -6.12 Resource: csourceSubscriptions/ [310](11-tabapi-http-binding.md#tabresource-csourcesubscriptions) - -6.12.1 Description [310](11-tabapi-http-binding.md#tabdescription-70) - -6.12.2 Resource definition [310](11-tabapi-http-binding.md#tabresource-definition-8) - -6.12.3 Resource methods [310](11-tabapi-http-binding.md#tabresource-methods-8) - -6.12.3.1 POST [310](11-tabapi-http-binding.md#tabpost-4) - -6.12.3.2 GET [311](11-tabapi-http-binding.md#tabget-6) - -6.13 Resource: csourceSubscriptions/{subscriptionId} [312](11-tabapi-http-binding.md#tabresource-csourcesubscriptionssubscriptionid) - -6.13.1 Description [312](11-tabapi-http-binding.md#tabdescription-71) - -6.13.2 Resource definition [312](11-tabapi-http-binding.md#tabresource-definition-9) - -6.13.3 Resource methods [312](11-tabapi-http-binding.md#tabresource-methods-9) - -6.13.3.1 GET [312](11-tabapi-http-binding.md#tabget-7) - -6.13.3.2 PATCH [313](11-tabapi-http-binding.md#tabpatch-5) - -6.13.3.3 DELETE [314](11-tabapi-http-binding.md#tabdelete-5) - -6.14 Resource: entityOperations/create [314](11-tabapi-http-binding.md#tabresource-entityoperationscreate) - -6.14.1 Description [314](11-tabapi-http-binding.md#tabdescription-72) - -6.14.2 Resource definition [315](11-tabapi-http-binding.md#tabresource-definition-10) - -6.14.3 Resource methods [315](11-tabapi-http-binding.md#tabresource-methods-10) - -6.14.3.1 POST [315](11-tabapi-http-binding.md#tabpost-5) - -6.15 Resource: entityOperations/upsert [316](11-tabapi-http-binding.md#tabresource-entityoperationsupsert) - -6.15.1 Description [316](11-tabapi-http-binding.md#tabdescription-73) - -6.15.2 Resource definition [316](11-tabapi-http-binding.md#tabresource-definition-11) - -6.15.3 Resource methods [317](11-tabapi-http-binding.md#tabresource-methods-11) - -6.15.3.1 POST [317](11-tabapi-http-binding.md#tabpost-6) - -6.16 Resource: entityOperations/update [318](11-tabapi-http-binding.md#tabresource-entityoperationsupdate) - -6.16.1 Description [318](11-tabapi-http-binding.md#tabdescription-74) - -6.16.2 Resource definition [319](11-tabapi-http-binding.md#tabresource-definition-12) - -6.16.3 Resource methods [319](11-tabapi-http-binding.md#tabresource-methods-12) - -6.16.3.1 POST [319](11-tabapi-http-binding.md#tabpost-7) - -6.17 Resource: entityOperations/delete [320](11-tabapi-http-binding.md#tabresource-entityoperationsdelete) - -6.17.1 Description [320](11-tabapi-http-binding.md#tabdescription-75) - -6.17.2 Resource definition [320](11-tabapi-http-binding.md#tabresource-definition-13) - -6.17.3 Resource methods [321](11-tabapi-http-binding.md#tabresource-methods-13) - -6.17.3.1 POST [321](11-tabapi-http-binding.md#tabpost-8) - -6.18 Resource: temporal/entities/ [322](11-tabapi-http-binding.md#tabresource-temporalentities) - -6.18.1 Description [322](11-tabapi-http-binding.md#tabdescription-76) - -6.18.2 Resource definition [322](11-tabapi-http-binding.md#tabresource-definition-14) - -6.18.3 Resource methods [323](11-tabapi-http-binding.md#tabresource-methods-14) - -6.18.3.1 POST [323](11-tabapi-http-binding.md#tabpost-9) - -6.18.3.2 GET [323](11-tabapi-http-binding.md#tabget-8) - -6.19 Resource: temporal/entities/{entityId} [327](11-tabapi-http-binding.md#tabresource-temporalentitiesentityid) - -6.19.1 Description [327](11-tabapi-http-binding.md#tabdescription-77) - -6.19.2 Resource definition [327](11-tabapi-http-binding.md#tabresource-definition-15) - -6.19.3 Resource methods [327](11-tabapi-http-binding.md#tabresource-methods-15) - -6.19.3.1 GET [327](11-tabapi-http-binding.md#tabget-9) - -6.19.3.2 DELETE [330](11-tabapi-http-binding.md#tabdelete-6) - -6.20 Resource: temporal/entities/{entityId}/attrs/ [331](11-tabapi-http-binding.md#tabresource-temporalentitiesentityidattrs) - -6.20.1 Description [331](11-tabapi-http-binding.md#tabdescription-78) - -6.20.2 Resource definition [331](11-tabapi-http-binding.md#tabresource-definition-16) - -6.20.3 Resource methods [331](11-tabapi-http-binding.md#tabresource-methods-16) - -6.20.3.1 POST [331](11-tabapi-http-binding.md#tabpost-10) - -6.21 Resource: temporal/entities/{entityId}/attrs/{attrId} [332](11-tabapi-http-binding.md#tabresource-temporalentitiesentityidattrsattrid) - -6.21.1 Description [332](11-tabapi-http-binding.md#tabdescription-79) - -6.21.2 Resource definition [332](11-tabapi-http-binding.md#tabresource-definition-17) - -6.21.3 Resource methods [332](11-tabapi-http-binding.md#tabresource-methods-17) - -6.21.3.1 DELETE [332](11-tabapi-http-binding.md#tabdelete-7) - -6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId} [333](11-tabapi-http-binding.md#tabresource-temporalentitiesentityidattrsattrid-instanceid) - -6.22.1 Description [333](11-tabapi-http-binding.md#tabdescription-80) - -6.22.2 Resource definition [333](11-tabapi-http-binding.md#tabresource-definition-18) - -6.22.3 Resource methods [334](11-tabapi-http-binding.md#tabresource-methods-18) - -6.22.3.1 PATCH [334](11-tabapi-http-binding.md#tabpatch-6) - -6.22.3.2 DELETE [334](11-tabapi-http-binding.md#tabdelete-8) - -6.23 Resource: entityOperations/query [335](11-tabapi-http-binding.md#tabresource-entityoperationsquery) - -6.23.1 Description [335](11-tabapi-http-binding.md#tabdescription-81) - -6.23.2 Resource definition [335](11-tabapi-http-binding.md#tabresource-definition-19) - -6.23.3 Resource methods [335](11-tabapi-http-binding.md#tabresource-methods-19) - -6.23.3.1 POST [335](11-tabapi-http-binding.md#tabpost-11) - -6.24 Resource: temporal/entityOperations/query [337](11-tabapi-http-binding.md#tabresource-temporalentityoperationsquery) - -6.24.1 Description [337](11-tabapi-http-binding.md#tabdescription-82) - -6.24.2 Resource definition [337](11-tabapi-http-binding.md#tabresource-definition-20) - -6.24.3 Resource methods [338](11-tabapi-http-binding.md#tabresource-methods-20) - -6.24.3.1 POST [338](11-tabapi-http-binding.md#tabpost-12) - -6.25 Resource: types/ [338](11-tabapi-http-binding.md#tabresource-types) - -6.25.1 Description [338](11-tabapi-http-binding.md#tabdescription-83) - -6.25.2 Resource definition [339](11-tabapi-http-binding.md#tabresource-definition-21) - -6.25.3 Resource methods [339](11-tabapi-http-binding.md#tabresource-methods-21) - -6.25.3.1 GET [339](11-tabapi-http-binding.md#tabget-10) - -6.26 Resource: types/{type} [340](11-tabapi-http-binding.md#tabresource-typestype) - -6.26.1 Description [340](11-tabapi-http-binding.md#tabdescription-84) - -6.26.2 Resource definition [340](11-tabapi-http-binding.md#tabresource-definition-22) - -6.26.3 Resource methods [340](11-tabapi-http-binding.md#tabresource-methods-22) - -6.26.3.1 GET [340](11-tabapi-http-binding.md#tabget-11) - -6.27 Resource: attributes/ [341](11-tabapi-http-binding.md#tabresource-attributes) - -6.27.1 Description [341](11-tabapi-http-binding.md#tabdescription-85) - -6.27.2 Resource definition [341](11-tabapi-http-binding.md#tabresource-definition-23) - -6.27.3 Resource methods [341](11-tabapi-http-binding.md#tabresource-methods-23) - -6.27.3.1 GET [341](11-tabapi-http-binding.md#tabget-12) - -6.28 Resource: attributes/{attrId} [342](11-tabapi-http-binding.md#tabresource-attributesattrid) - -6.28.1 Description [342](11-tabapi-http-binding.md#tabdescription-86) - -6.28.2 Resource definition [342](11-tabapi-http-binding.md#tabresource-definition-24) - -6.28.3 Resource methods [342](11-tabapi-http-binding.md#tabresource-methods-24) - -6.28.3.1 GET [342](11-tabapi-http-binding.md#tabget-13) - -6.29 Resource: jsonldContexts/ [343](11-tabapi-http-binding.md#tabresource-jsonldcontexts) - -6.29.1 Description [343](11-tabapi-http-binding.md#tabdescription-87) - -6.29.2 Resource definition [343](11-tabapi-http-binding.md#tabresource-definition-25) - -6.29.3 Resource methods [343](11-tabapi-http-binding.md#tabresource-methods-25) - -6.29.3.1 POST [343](11-tabapi-http-binding.md#tabpost-13) - -6.29.3.2 GET [344](11-tabapi-http-binding.md#tabget-14) - -6.30 Resource: jsonldContexts/{contextId} [345](11-tabapi-http-binding.md#tabresource-jsonldcontextscontextid) - -6.30.1 Description [345](11-tabapi-http-binding.md#tabdescription-88) - -6.30.2 Resource definition [345](11-tabapi-http-binding.md#tabresource-definition-26) - -6.30.3 Resource methods [345](11-tabapi-http-binding.md#tabresource-methods-26) - -6.30.3.1 GET [345](11-tabapi-http-binding.md#tabget-15) - -6.30.3.2 DELETE [346](11-tabapi-http-binding.md#tabdelete-9) - -6.31 Resource: entityOperations/merge [347](11-tabapi-http-binding.md#tabresource-entityoperationsmerge) - -6.31.1 Description [347](11-tabapi-http-binding.md#tabdescription-89) - -6.31.2 Resource definition [347](11-tabapi-http-binding.md#tabresource-definition-27) - -6.31.3 Resource methods [347](11-tabapi-http-binding.md#tabresource-methods-27) - -6.31.3.1 POST [347](11-tabapi-http-binding.md#tabpost-14) - -6.32 Resource: entityMaps/{entityMapId} [349](11-tabapi-http-binding.md#tabresource-entitymapsentitymapid) - -6.32.1 Description [349](11-tabapi-http-binding.md#tabdescription-90) - -6.32.2 Resource definition [349](11-tabapi-http-binding.md#tabresource-definition-28) - -6.32.3 Resource methods [349](11-tabapi-http-binding.md#tabresource-methods-28) - -6.32.3.1 GET [349](11-tabapi-http-binding.md#tabget-16) - -6.32.3.2 PATCH [350](11-tabapi-http-binding.md#tabpatch-7) - -6.32.3.3 DELETE [350](11-tabapi-http-binding.md#tabdelete-10) - -6.33 Resource: info/sourceIdentity [351](11-tabapi-http-binding.md#tabresource-infosourceidentity) - -6.33.1 Description [351](11-tabapi-http-binding.md#tabdescription-91) - -6.33.2 Resource definition [351](11-tabapi-http-binding.md#tabresource-definition-29) - -6.33.3 Resource methods [351](11-tabapi-http-binding.md#tabresource-methods-29) - -6.33.3.1 GET [351](11-tabapi-http-binding.md#tabget-17) - -6.34 Resource: entityMaps [352](11-tabapi-http-binding.md#tabresource-entitymaps) - -6.34.1 Description [352](11-tabapi-http-binding.md#tabdescription-92) - -6.34.2 Resource definition [352](11-tabapi-http-binding.md#tabresource-definition-30) - -6.34.3 Resource methods [352](11-tabapi-http-binding.md#tabresource-methods-30) - -6.34.3.1 GET [352](11-tabapi-http-binding.md#tabget-18) - -6.34.3.2 POST [353](11-tabapi-http-binding.md#tabpost-15) - -6.35 Resource: temporal/entityMaps [354](11-tabapi-http-binding.md#tabresource-temporalentitymaps) - -6.35.1 Description [354](11-tabapi-http-binding.md#tabdescription-93) - -6.35.2 Resource definition [354](11-tabapi-http-binding.md#tabresource-definition-31) - -6.35.3 Resource methods [354](11-tabapi-http-binding.md#tabresource-methods-31) - -6.35.3.1 GET [354](11-tabapi-http-binding.md#tabget-19) - -6.35.3.2 POST [355](11-tabapi-http-binding.md#tabpost-16) - -6.36 Resource: snapshots [356](11-tabapi-http-binding.md#tabresource-snapshots) - -6.36.1 Description [356](11-tabapi-http-binding.md#tabdescription-94) - -6.36.2 Resource definition [356](11-tabapi-http-binding.md#tabresource-definition-32) - -6.36.3 Resource methods [356](11-tabapi-http-binding.md#tabresource-methods-32) - -6.36.3.1 POST [356](11-tabapi-http-binding.md#tabpost-17) - -6.36.3.2 DELETE [357](11-tabapi-http-binding.md#tabdelete-11) - -6.37 Resource: snapshots/{snapshotId} [358](11-tabapi-http-binding.md#tabresource-snapshotssnapshotid) - -6.37.1 Description [358](11-tabapi-http-binding.md#tabdescription-95) - -6.37.2 Resource definition [358](11-tabapi-http-binding.md#tabresource-definition-33) - -6.37.3 Resource methods [358](11-tabapi-http-binding.md#tabresource-methods-33) - -6.37.3.1 GET [358](11-tabapi-http-binding.md#tabget-20) - -6.37.3.2 PATCH [359](11-tabapi-http-binding.md#tabpatch-8) - -6.37.3.3 DELETE [359](11-tabapi-http-binding.md#tabdelete-12) - -6.38 Resource: snapshots/{snapshotId}/clone [360](11-tabapi-http-binding.md#tabresource-snapshotssnapshotidclone) - -6.38.1 Description [360](11-tabapi-http-binding.md#tabdescription-96) - -6.38.2 Resource definition [360](11-tabapi-http-binding.md#tabresource-definition-34) - -6.38.3 Resource methods [360](11-tabapi-http-binding.md#tabresource-methods-34) - -6.38.3.1 POST [360](11-tabapi-http-binding.md#tabpost-18) - -7 API MQTT Notification Binding [361](12-tabapi-mqtt-notification-binding.md#tabapi-mqtt-notification-binding) - -7.1 Introduction [361](12-tabapi-mqtt-notification-binding.md#tabintroduction-23) - -7.2 Notification behaviour [361](12-tabapi-mqtt-notification-binding.md#tabnotification-behaviour-3) - -[Annex A](13-annex-a-normative-ngsi-ld-identifier-considerations.md#annex-a-normative-ngsi-ld-identifier-considerations) (normative): NGSI-LD identifier considerations [363](13-annex-a-normative-ngsi-ld-identifier-considerations.md#annex-a-normative-ngsi-ld-identifier-considerations) - -A.1 Introduction [363](13-annex-a-normative-ngsi-ld-identifier-considerations.md#a.1tabintroduction) - -A.2 Entity identifiers [363](13-annex-a-normative-ngsi-ld-identifier-considerations.md#a.2tabentity-identifiers) - -A.3 NGSI-LD namespace [363](13-annex-a-normative-ngsi-ld-identifier-considerations.md#a.3tabngsi-ld-namespace) - -[Annex B](14-annex-b-normative-core-ngsi-ld-context-definition.md#annex-b-normative-core-ngsi-ld-context-definition) (normative): Core NGSI-LD \@context definition [364](14-annex-b-normative-core-ngsi-ld-context-definition.md#annex-b-normative-core-ngsi-ld-context-definition) - -[Annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api) (informative): Examples of using the API [370](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api) - -C.1 Introduction [370](15-annex-c-informative-examples-of-using-the-api.md#c.1tabintroduction) - -C.2 Entity Representation [370](15-annex-c-informative-examples-of-using-the-api.md#c.2tabentity-representation) - -C.2.1 Property Graph [370](15-annex-c-informative-examples-of-using-the-api.md#c.2.1tabproperty-graph) - -C.2.2 Vehicle Entity [371](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity) - -C.2.3 Parking Entity [384](15-annex-c-informative-examples-of-using-the-api.md#c.2.3tabparking-entity) - -C.2.4 \@context [390](15-annex-c-informative-examples-of-using-the-api.md#c.2.4tabcontext) - -C.3 Context Source Registration [391](15-annex-c-informative-examples-of-using-the-api.md#c.3tabcontext-source-registration) - -C.4 Context Subscription [391](15-annex-c-informative-examples-of-using-the-api.md#c.4tabcontext-subscription) - -C.5 HTTP REST API Examples [392](15-annex-c-informative-examples-of-using-the-api.md#c.5tabhttp-rest-api-examples) - -C.5.1 Introduction [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.1tabintroduction) - -C.5.2 Create Entity of Type Vehicle [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.2tabcreate-entity-of-type-vehicle) - -C.5.2.1 HTTP Request [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.2.1tabhttp-request) - -C.5.2.2 HTTP Response [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.2.2tabhttp-response) - -C.5.3 Query Entities [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.3tabquery-entities) - -C.5.3.1 Introduction [392](15-annex-c-informative-examples-of-using-the-api.md#c.5.3.1tabintroduction) - -C.5.3.2 HTTP Request [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.3.2tabhttp-request) - -C.5.3.3 HTTP Response [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.3.3tabhttp-response) - -C.5.4 Query Entities (Pagination) [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.4tabquery-entities-pagination) - -C.5.4.1 Introduction [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.4.1tabintroduction) - -C.5.4.2 HTTP Request [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.4.2tabhttp-request) - -C.5.4.3 HTTP Response [393](15-annex-c-informative-examples-of-using-the-api.md#c.5.4.3tabhttp-response) - -C.5.5 Temporal Query [394](15-annex-c-informative-examples-of-using-the-api.md#c.5.5tabtemporal-query) - -C.5.5.1 Introduction [394](15-annex-c-informative-examples-of-using-the-api.md#c.5.5.1tabintroduction) - -C.5.5.2 HTTP Request #1 [394](15-annex-c-informative-examples-of-using-the-api.md#c.5.5.2tabhttp-request-1) - -C.5.5.3 HTTP Response #1 [394](15-annex-c-informative-examples-of-using-the-api.md#c.5.5.3tabhttp-response-1) - -C.5.5.4 HTTP Request #2 [395](15-annex-c-informative-examples-of-using-the-api.md#c.5.5.4tabhttp-request-2) - -C.5.5.5 HTTP Response #2 [395](15-annex-c-informative-examples-of-using-the-api.md#c.5.5.5tabhttp-response-2) - -C.5.6 Temporal Query (Simplified Representation) [395](15-annex-c-informative-examples-of-using-the-api.md#c.5.6tabtemporal-query-simplified-representation) - -C.5.6.1 Introduction [395](15-annex-c-informative-examples-of-using-the-api.md#c.5.6.1tabintroduction) - -C.5.6.2 HTTP Request [395](15-annex-c-informative-examples-of-using-the-api.md#c.5.6.2tabhttp-request) - -C.5.6.3 HTTP Response [396](15-annex-c-informative-examples-of-using-the-api.md#c.5.6.3tabhttp-response) - -C.5.7 Retrieve Available Entity Types [396](15-annex-c-informative-examples-of-using-the-api.md#c.5.7tabretrieve-available-entity-types) - -C.5.7.1 Introduction [396](15-annex-c-informative-examples-of-using-the-api.md#c.5.7.1tabintroduction) - -C.5.7.2 HTTP Request [396](15-annex-c-informative-examples-of-using-the-api.md#c.5.7.2tabhttp-request) - -C.5.7.3 HTTP Response [396](15-annex-c-informative-examples-of-using-the-api.md#c.5.7.3tabhttp-response) - -C.5.8 Retrieve Details of Available Entity Types [397](15-annex-c-informative-examples-of-using-the-api.md#c.5.8tabretrieve-details-of-available-entity-types) - -C.5.8.1 Introduction [397](15-annex-c-informative-examples-of-using-the-api.md#c.5.8.1tabintroduction) - -C.5.8.2 HTTP Request [397](15-annex-c-informative-examples-of-using-the-api.md#c.5.8.2tabhttp-request) - -C.5.8.3 HTTP Response [397](15-annex-c-informative-examples-of-using-the-api.md#c.5.8.3tabhttp-response) - -C.5.9 Retrieve Available Entity Type Information [398](15-annex-c-informative-examples-of-using-the-api.md#c.5.9tabretrieve-available-entity-type-information) - -C.5.9.1 Introduction [398](15-annex-c-informative-examples-of-using-the-api.md#c.5.9.1tabintroduction) - -C.5.9.2 HTTP Request [398](15-annex-c-informative-examples-of-using-the-api.md#c.5.9.2tabhttp-request) - -C.5.9.3 HTTP Response [398](15-annex-c-informative-examples-of-using-the-api.md#c.5.9.3tabhttp-response) - -C.5.10 Retrieve Available Attributes [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.10tabretrieve-available-attributes) - -C.5.10.1 Introduction [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.10.1tabintroduction) - -C.5.10.2 HTTP Request [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.10.2tabhttp-request) - -C.5.10.3 HTTP Response [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.10.3tabhttp-response) - -C.5.11 Retrieve Details of Available Attributes [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.11tabretrieve-details-of-available-attributes) - -C.5.11.1 Introduction [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.11.1tabintroduction) - -C.5.11.2 HTTP Request [399](15-annex-c-informative-examples-of-using-the-api.md#c.5.11.2tabhttp-request) - -C.5.11.3 HTTP Response [400](15-annex-c-informative-examples-of-using-the-api.md#c.5.11.3tabhttp-response) - -C.5.12 Retrieve Available Attribute Information [400](15-annex-c-informative-examples-of-using-the-api.md#c.5.12tabretrieve-available-attribute-information) - -C.5.12.1 Introduction [400](15-annex-c-informative-examples-of-using-the-api.md#c.5.12.1tabintroduction) - -C.5.12.2 HTTP Request [400](15-annex-c-informative-examples-of-using-the-api.md#c.5.12.2tabhttp-request) - -C.5.12.3 HTTP Response [401](15-annex-c-informative-examples-of-using-the-api.md#c.5.12.3tabhttp-response) - -C.5.13 Query Entities (Natural Language Filtering) [401](15-annex-c-informative-examples-of-using-the-api.md#c.5.13tabquery-entities-natural-language-filtering) - -C.5.13.1 Introduction [401](15-annex-c-informative-examples-of-using-the-api.md#c.5.13.1tabintroduction) - -C.5.13.2 HTTP Request [401](15-annex-c-informative-examples-of-using-the-api.md#c.5.13.2tabhttp-request) - -C.5.13.3 HTTP Response [401](15-annex-c-informative-examples-of-using-the-api.md#c.5.13.3tabhttp-response) - -C.5.14 Temporal Query (Aggregated Representation) [402](15-annex-c-informative-examples-of-using-the-api.md#c.5.14tabtemporal-query-aggregated-representation) - -C.5.14.1 Introduction [402](15-annex-c-informative-examples-of-using-the-api.md#c.5.14.1tabintroduction) - -C.5.14.2 HTTP Request [402](15-annex-c-informative-examples-of-using-the-api.md#c.5.14.2tabhttp-request) - -C.5.14.3 HTTP Response [402](15-annex-c-informative-examples-of-using-the-api.md#c.5.14.3tabhttp-response) - -C.5.15 Scope Queries [403](15-annex-c-informative-examples-of-using-the-api.md#c.5.15tabscope-queries) - -C.5.15.1 Introduction [403](15-annex-c-informative-examples-of-using-the-api.md#c.5.15.1tabintroduction) - -C.5.15.2 HTTP Request [403](15-annex-c-informative-examples-of-using-the-api.md#c.5.15.2tabhttp-request) - -C.5.15.3 HTTP Response [403](15-annex-c-informative-examples-of-using-the-api.md#c.5.15.3tabhttp-response) - -C.5.16 Temporal Scope Queries [404](15-annex-c-informative-examples-of-using-the-api.md#c.5.16tabtemporal-scope-queries) - -C.5.16.1 Introduction [404](15-annex-c-informative-examples-of-using-the-api.md#c.5.16.1tabintroduction) - -C.5.16.2 HTTP Request [404](15-annex-c-informative-examples-of-using-the-api.md#c.5.16.2tabhttp-request) - -C.5.16.3 HTTP Response [404](15-annex-c-informative-examples-of-using-the-api.md#c.5.16.3tabhttp-response) - -C.6 Date Representation [406](15-annex-c-informative-examples-of-using-the-api.md#c.6tabdate-representation) - -C.7 \@context utilization clarifications [407](15-annex-c-informative-examples-of-using-the-api.md#c.7tabcontext-utilization-clarifications) - -C.8 Link header utilization clarifications [408](15-annex-c-informative-examples-of-using-the-api.md#c.8tablink-header-utilization-clarifications) - -C.9 \@context processing clarifications [410](15-annex-c-informative-examples-of-using-the-api.md#c.9tabcontext-processing-clarifications) - -C.10 ValueType datatype utilization clarifications [411](15-annex-c-informative-examples-of-using-the-api.md#c.10tabvaluetype-datatype-utilization-clarifications) - -C.11 Entity with digital signature for a Property [411](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) - -[Annex D](16-annex-d-informative-transformation-algorithms.md#annex-d-informative-transformation-algorithms) (informative): Transformation Algorithms [413](16-annex-d-informative-transformation-algorithms.md#annex-d-informative-transformation-algorithms) - -D.1 Introduction [413](16-annex-d-informative-transformation-algorithms.md#d.1tabintroduction) - -D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) [413](16-annex-d-informative-transformation-algorithms.md#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1) - -D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1) [414](16-annex-d-informative-transformation-algorithms.md#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1) - -D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2) [415](16-annex-d-informative-transformation-algorithms.md#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2) - -[Annex E](17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.md#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model) (informative): RDF-compatible specification of NGSI-LD meta-model [416](17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.md#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model) - -[Annex F](18-annex-f-informative-conventions-and-syntax-guidelines.md#annex-f-informative-conventions-and-syntax-guidelines) (informative): Conventions and syntax guidelines [417](18-annex-f-informative-conventions-and-syntax-guidelines.md#annex-f-informative-conventions-and-syntax-guidelines) - -[Annex G](19-annex-g-informative-localization-and-internationalization-support.md#annex-g-informative-localization-and-internationalization-support) (informative): Localization and Internationalization Support [418](19-annex-g-informative-localization-and-internationalization-support.md#annex-g-informative-localization-and-internationalization-support) - -G.0 Foreword [418](19-annex-g-informative-localization-and-internationalization-support.md#g.0tabforeword) - -G.1 Introduction [418](19-annex-g-informative-localization-and-internationalization-support.md#g.1tabintroduction) - -G.1.0 Foreword [418](19-annex-g-informative-localization-and-internationalization-support.md#g.1.0tabforeword) - -G.1.1 Associating an Entity with a Natural Language [418](19-annex-g-informative-localization-and-internationalization-support.md#g.1.1tabassociating-an-entity-with-a-natural-language) - -G.1.2 Associating a Property with a Natural Language [418](19-annex-g-informative-localization-and-internationalization-support.md#g.1.2tabassociating-a-property-with-a-natural-language) - -G.1.3 Associating as equivalent entity [419](19-annex-g-informative-localization-and-internationalization-support.md#g.1.3tabassociating-as-equivalent-entity) - -G.2 Natural Language Collation Support [419](19-annex-g-informative-localization-and-internationalization-support.md#g.2tabnatural-language-collation-support) - -G.2.0 Foreword [419](19-annex-g-informative-localization-and-internationalization-support.md#g.2.0tabforeword) - -G.2.1 Maintain collations as metadata [420](19-annex-g-informative-localization-and-internationalization-support.md#g.2.1tabmaintain-collations-as-metadata) - -G.2.2 Route language sensitive queries via a proxy [420](19-annex-g-informative-localization-and-internationalization-support.md#g.2.2tabroute-language-sensitive-queries-via-a-proxy) - -G.3 Localization of Dates, Currency formats, etc. [420](19-annex-g-informative-localization-and-internationalization-support.md#g.3tablocalization-of-dates-currency-formats-etc.) - -G.3.0 Foreword [420](19-annex-g-informative-localization-and-internationalization-support.md#g.3.0tabforeword) - -G.3.1 Localizing Dates [420](19-annex-g-informative-localization-and-internationalization-support.md#g.3.1tablocalizing-dates) - -[Annex H](20-annex-h-informative-suggested-actuation-workflows.md#annex-h-informative-suggested-actuation-workflows) (informative): Suggested actuation workflows [422](20-annex-h-informative-suggested-actuation-workflows.md#annex-h-informative-suggested-actuation-workflows) - -H.1 Actuators and feedback to the consumer [422](20-annex-h-informative-suggested-actuation-workflows.md#h.1tabactuators-and-feedback-to-the-consumer) - -H.2 Architecture for actuation [422](20-annex-h-informative-suggested-actuation-workflows.md#h.2tabarchitecture-for-actuation) - -H.3 Structure of Commands and additional Properties [423](20-annex-h-informative-suggested-actuation-workflows.md#h.3tabstructure-of-commands-and-additional-properties) - -H.3.0 Introduction [423](20-annex-h-informative-suggested-actuation-workflows.md#h.3.0tabintroduction) - -H.3.1 Property for listing available commands [424](20-annex-h-informative-suggested-actuation-workflows.md#h.3.1tabproperty-for-listing-available-commands) - -H.3.2 Properties for command endpoints [424](20-annex-h-informative-suggested-actuation-workflows.md#h.3.2tabproperties-for-command-endpoints) - -H.4 Communication model [426](20-annex-h-informative-suggested-actuation-workflows.md#h.4tabcommunication-model) - -H.4.1 Possible communication models [426](20-annex-h-informative-suggested-actuation-workflows.md#h.4.1tabpossible-communication-models) - -H.4.2 Subscription/notification model [426](20-annex-h-informative-suggested-actuation-workflows.md#h.4.2tabsubscriptionnotification-model) - -H.4.3 Forwarding model [427](20-annex-h-informative-suggested-actuation-workflows.md#h.4.3tabforwarding-model) - -H.5 Implementation of the subscription-based actuation workflow [428](20-annex-h-informative-suggested-actuation-workflows.md#h.5tabimplementation-of-the-subscription-based-actuation-workflow) - -H.6 Implementation of the registration-based actuation workflow [429](20-annex-h-informative-suggested-actuation-workflows.md#h.6tabimplementation-of-the-registration-based-actuation-workflow) - -[Annex I](21-annex-i-informative-change-history.md#annex-i-informative-change-history) (informative): Change history [432](21-annex-i-informative-change-history.md#annex-i-informative-change-history) - -History [435](22-history.md#history) diff --git a/API-md/1-intellectual-property-rights.md b/API-md/1-intellectual-property-rights.md deleted file mode 100644 index 4239caae1de3b860575c8371469269e40133bc31..0000000000000000000000000000000000000000 --- a/API-md/1-intellectual-property-rights.md +++ /dev/null @@ -1,17 +0,0 @@ -# Intellectual Property Rights {#intellectual-property-rights number="1"} - -::: H6 -Essential patents -::: - -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 IPR online database](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. - -::: H6 -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 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™**, **LTE™** and **5G™** logo 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. diff --git a/API-md/10-tabapi-operation-definition.md b/API-md/10-tabapi-operation-definition.md deleted file mode 100644 index bea338c58c051b001b35dfb84fa0f28d0ad55f94..0000000000000000000000000000000000000000 --- a/API-md/10-tabapi-operation-definition.md +++ /dev/null @@ -1,6868 +0,0 @@ -# 5 API Operation Definition {#tabapi-operation-definition number="10"} - -## 5.1 Introduction {#tabintroduction-15 number="10.1"} - -This clause defines data structures and operations of the NGSI-LD API. No specific binding is assumed. [Clause 6](11-tabapi-http-binding.md#tabapi-http-binding) maps these operations and data types to the HTTP REST binding. - -::: NO -NOTE: - -In UML diagrams dotted arrows denote a response to a request. -::: - -## 5.2 Data Types {#tabdata-types number="10.2"} - -### 5.2.1 Introduction {#tabintroduction-16 number="10.2.1"} - -Implementations shall support the data types defined by the clauses below. For each member defined by each data type (including nested ones) a term shall be added to the Core *\@context*, as mandated by [clause 4.5](9-tabcontext-information-management-framework.md#tabngsi-ld-data-representation). - -None of the members described admit a *null* value directly, as when a JSON-LD processor encounters *null*, the associated entry or value is always removed when expanding the JSON-LD document. - -However, in the context of a partial update or merge operation (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)), an NGSI-LD Null shall be used to indicate the removal of a target member, as explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4). In all other cases, implementations shall raise an error of type *BadRequestData* if an NGSI-LD Null value is encountered. - -As *null* cannot be used as a value in JSON-LD, there is still the possibility of using a JSON null literal [{"@type": "@json", "@value": null} ]{.HTML_Code}instead. JSON literals are not to be expanded in JSON-LD and thus the respective element is not removed during JSON-LD expansion. - -Non-normative JSON Schema [[i.11]](7-tabreferences.md#i.11) definitions of the referred data types are also available at [[i.13]](7-tabreferences.md#i.13). - -The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [[23]](7-tabreferences.md#23), which extends the use of characters to Unicode characters [[22]](7-tabreferences.md#22) beyond the ASCII character set, enabling the support of languages other than English. - -### 5.2.2 Common members {#tabcommon-members number="10.2.2"} - -The JSON-LD representation of NGSI-LD Entity, Property, Relationship, [Context Source Registration]{.HTML_Keyboard} and Subscription can include the common members described by [Table 5.2.2‑1](10-tabapi-operation-definition.md#Table_5.2.2-1). - -Those members are read-only, and shall be automatically generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -In query or retrieve operations implementations shall only generate common members [(Table 5.2.2‑1](10-tabapi-operation-definition.md#Table_5.2.2-1)) when the [Context Consumer]{.HTML_Keyboard}explicitly asks for their inclusion. [Clause 6.3.11](11-tabapi-http-binding.md#tabincluding-system-attributes) defines the mechanism offered by the HTTP binding for such purpose. - -::: {#Table_5.2.2-1 .TH} -Table 5.2.2-1: Common members of NGSI-LD elements -::: - -::: TAL -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=============+====================================================================================================================+=============+====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| createdAt | string | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Entity creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | string | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Entity deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). It is only used in notifications reporting deletions and in the temporal representation of Entities [(clause 4.5.6](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-an-entity)), Properties [(clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property)), Relationships [(clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship)) and [LanguageProperties]{.HTML_Keyboard} [(clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty)) and [VocabProperties]{.HTML_Keyboard} [(clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty)) and [JsonProperties]{.HTML_Keyboard} [(clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty)). | -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | string | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Entity last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.3 \@context {#tabcontext number="10.2.3"} - -When encoding NGSI-LD Entities, [Context Source Registrations]{.HTML_Keyboard}, Subscriptions and Notifications, as pure JSON-LD (MIME type ["application/ld+json"),]{.HTML_Code} - -an array (flattened to a single string if necessary), containing a user - -*\@context* - -where present, and the core - -*\@context* (as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context)) shall be included as a special member of the corresponding JSON-LD Object. [Table 5.2.3‑1](10-tabapi-operation-definition.md#Table_5.2.3-1) gives a precise definition of this special member. - -::: {#Table_5.2.3-1 .TH} -Table 5.2.3-1: JSON-LD \@context tagged member -::: - -::: TAL -+-------------+---------------------------------+---------------------------------------------------+-------------+----------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=================================+===================================================+=============+======================+ -| \@context | URI, JSON Object, or JSON Array | See [[2]](7-tabreferences.md#2), section 5.1. | 0..1 | JSON-LD *\@context*. | -+-------------+---------------------------------+---------------------------------------------------+-------------+----------------------+ -::: - -### 5.2.4 Entity {#tabentity number="10.2.4"} - -This type represents the data needed to define an NGSI-LD Entity as mandated by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.4‑1](10-tabapi-operation-definition.md#Table_5.2.4-1). - -::: {#Table_5.2.4-1 .TH} -Table 5.2.4-1: NGSI-LD Entity data type definition -::: - -::: TAL -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+==================================+=======================================================+========================================================================================================================+==============================================================================+=================================================================================================================================================================================================================+ -| id | String | Valid URI | 1 | Entity ID. | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String or String[] | 1 | Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. | | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the Entity. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| location | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..1 | Default geospatial Property of an entity. See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observationSpace | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..1 | See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| operationSpace | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..1 | See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scope | String or String[] | See [clause 4.18](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes) | 0..1 | Scope. | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 1) | See datatype definitions in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Property as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty or GeoProperty[] (see note 1) | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | GeoProperty as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | LanguageProperty as mandated by [clause 4.5.18](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | JsonProperty as mandated by [clause 4.5.24](9-tabcontext-information-management-framework.md#tabngsi-ld-jsonproperty-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | VocabProperty as mandated by [clause 4.5.20](9-tabcontext-information-management-framework.md#tabngsi-ld-vocabproperty-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListProperty or ListProperty[] (see note 1) | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | ListProperty as mandated by [clause 4.5.21](9-tabcontext-information-management-framework.md#tabngsi-ld-listproperty-representations). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[] (see note 2) | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationship as mandated by [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). | -| +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | ListRelationship as mandated by [clause 4.5.22](9-tabcontext-information-management-framework.md#tabngsi-ld-listrelationship-representations). | -+----------------------------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId* . | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId* . | -| ::: | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.5 Property {#tabproperty number="10.2.5"} - -This type represents the data needed to define a *Property* as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). - -The supported JSON members shall follow the requirements provided in [Table 5.2.5‑1](10-tabapi-operation-definition.md#Table_5.2.5-1) below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute *type* member can be omitted as [type="Property"]{.HTML_Code} can be inferred from the presence of the *value* member. Furthermore, in the concise representation of a *Property*, the *value* member cannot be a GeoJSON Object (as defined in [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties)) as it would be interpreted as a *GeoProperty* (see [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty)). - -::: {#Table_5.2.5-1 .TH} -Table 5.2.5-1: NGSI-LD Property data type definition -::: - -::: TAL -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+===============================================================================================+==============================================================================================================================================================================================================================================================================================+==============================================================================================================================================================+===================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["Property"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| value | Any JSON value as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | See NGSI-LD Value definition in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms). | 1 | Property Value. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the Property. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the Property guaranteeing its integrity. See [clause C.11](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) for an example. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| unitCode | String | As mandated by [[15]](7-tabreferences.md#15) | 0..1 | Property Value's unit code. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | 0..1 | The native JSON-LD *\@type* for the Property Value. A String Value which shall be type coerced to a URI based on the supplied *\@context*[.]{.HTML_Variable} | | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 1) | See datatype definition in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty or GeoProperty[] (see note 1) | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | GeoProperties of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | LanguageProperties of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | JsonProperties of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | VocabProperties of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListProperty]{.HTML_Definition} or [ListProperty]{.HTML_Definition}[] (see note 1) | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | ListProperties of the Property. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[] (see note 2) | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the Property. | -| +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListRelationship]{.HTML_Definition} or [ListRelationship]{.HTML_Definition}[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | ListRelationships of the Property. | -+-------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.5-2) of the *Property* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.5-2 .TH} -Table 5.2.5-2: Output only members of the NGSI-LD Property data type -::: - -::: TAL -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===============+============================================================================+====================================================================================================================+=============+==========================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of Properties | 0..1 | URI uniquely identifying a Property instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousValue | Any JSON value as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | Only used in Notifications, if the *showChanges* option is explicitly requested | 0..1 | Previous Property Value. | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.6 Relationship {#tabrelationship number="10.2.6"} - -This type represents the data needed to define a *Relationship* as mandated by [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). - -The supported JSON members shall follow the requirements provided in [Table 5.2.6‑1](10-tabapi-operation-definition.md#Table_5.2.6-1) below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute *type*member can be omitted as [type="Relationship"]{.HTML_Code} can be inferred from the presence of the *object* member. - -::: {#Table_5.2.6-1 .TH} -Table 5.2.6-1: NGSI-LD Relationship data type definition -::: - -::: TAL -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+=======================================================+==============================================================================================================================================================================================================================================================================================+==============================================================================================================+=======================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["Relationship"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| object | String or String[] | Valid URI or an Array of Valid URIs | 1 | Relationship's target object. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of target relationship objects. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the Relationship. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the Relationship guaranteeing its integrity. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| objectType | String or String[] | 0..1 | Node Type of the Relationship's target object. Both short hand string(s) (type name) or URI(s) are allowed. | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 1) | See datatype definition in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty or GeoProperty[] (see note 1) | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | GeoProperties of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | LanguageProperties of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | JsonProperties of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | VocabProperties of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListProperty or ListProperty[] (see note 1) | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | ListProperties of the Relationship. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[] (see note 2) | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the Relationship. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | ListRelationships of the Relationship. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.6-2) of the *Relationship* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.6-2 .TH} -Table 5.2.6-2: Output only members of the NGSI-LD Relationship data type -::: - -::: TAL -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===========================+=================================+====================================================================================================================+===========================+=============================================================================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entity | Entity or Entity[] (see note) | See datatype definition in [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). | 0..1 | An inline Entity obtained by Linked Entity Retrieval, corresponding to the Relationship's target object. See [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation). | -| | | | | | -| | | Only used in Linked Entity Retrieval, if the *join=inline* option is explicitly requested | | | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of Relationships | 0..1 | URI uniquely identifying a Relationship instance as mandated by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousObject | String | Valid URI. Only used in Notifications, if the *showChanges* option is explicitly requested | 0..1 | Previous Relationship's target object. | -+---------------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE: | -| | -| one-to-N *Relationships* expand to an array of Entity elements, since there can be more than one target object URI specified. | -| ::: | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.7 GeoProperty {#tabgeoproperty number="10.2.7"} - -This type represents the data needed to define a *GeoProperty*. - -The supported JSON members shall follow the requirements provided in [Table 5.2.7‑1](10-tabapi-operation-definition.md#Table_5.2.7-1) below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute *type* member can be omitted as ["GeoProperty"]{.HTML_Code} can be inferred from the presence of the *value* member holding a GeoJSON *Geometry* as mandated by [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties). - -::: {#Table_5.2.7-1 .TH} -Table 5.2.7-1: NGSI-LD GeoProperty data type definition -::: - -::: TAL -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+========================================================================================================================================================+==============================================================================================================================================================================================================================================================================================+=================================================================================================================================================================+========================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["GeoProperty"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| value | JSON Object | As mandated by [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 1 | Geolocation encoded as GeoJSON [[8]](7-tabreferences.md#8). | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [GeoProperty]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the GeoProperty guaranteeing its integrity. | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | 0..1 | The native JSON-LD *\@type* for the GeoProperty Value. A String Value which shall be type coerced to a URI based on the supplied *\@context*[.]{.HTML_Variable} | | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 1) | [See datatype definition in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [Properties of the ]{.ondemand_CHAR_size_9}[GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty or GeoProperty[] (see note 1) | [See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [GeoProperties]{.ondemand_CHAR_name_Arial_size_9}[of the ]{.ondemand_CHAR_size_9}[GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [LanguageProperty or LanguageProperty[] ]{.ondemand_CHAR_size_9}([see note 1]{.ondemand_CHAR_size_9}) | [See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [LanguageProperties]{.ondemand_CHAR_name_Arial_size_9}[of the ]{.ondemand_CHAR_size_9}[GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [JsonProperty or JsonProperty[](see note 1)]{.ondemand_CHAR_name_Arial_size_9} | [See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty)]{.ondemand_CHAR_name_Arial_size_9} | [0..N]{.ondemand_CHAR_name_Arial_size_9} | [JsonProperties of the GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [VocabProperty or VocabProperty]{.ondemand_CHAR_name_Arial_size_9}[[] ]{.ondemand_CHAR_size_9}[(see note 1)]{.ondemand_CHAR_name_Arial_size_9} | [See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [VocabProperties]{.ondemand_CHAR_name_Arial_size_9}[of the ]{.ondemand_CHAR_size_9}[GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListProperty or ListProperty[] (see note 1) | [See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [ListProperties of the GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[] (see note 2) | [See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [Relationships of the ]{.ondemand_CHAR_size_9}[GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -| +--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListRelationship or ListRelationship]{.ondemand_CHAR_name_Arial_size_9}[[] ]{.ondemand_CHAR_size_9}[(see note 2)]{.ondemand_CHAR_name_Arial_size_9} | [See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship)]{.ondemand_CHAR_size_9} | [0..N]{.ondemand_CHAR_size_9} | [ListRelationships of the GeoProperty.]{.ondemand_CHAR_name_Arial_size_9} | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.7-2) of the *GeoProperty* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.7-2 .TH} -Table 5.2.7-2: Output only members of the NGSI-LD GeoProperty data type -::: - -::: TAL -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===============+============================================================================+====================================================================================================================+=============+=============================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of GeoProperties | 0..1 | URI uniquely identifying a GeoProperty instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | DateTime[(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousValue | Any JSON value as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | Only used in [Notifications]{.HTML_Keyboard}, if the *showChanges* option is explicitly requested | 0..1 | Previous GeoProperty Value. | -+---------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.8 EntityInfo {#tabentityinfo number="10.2.8"} - -This type represents what Entities, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [[11]](7-tabreferences.md#11)) can be provided (by [Context Sources]{.HTML_Keyboard}). - -The JSON members shall follow the indications provided in [Table 5.2.8‑1](10-tabapi-operation-definition.md#Table_5.2.8-1). *id* takes precedence over *idPattern*. - -Notice that Cardinality of *type* being 1 implies that it is not possible to register what Entities can be provided by a [Context Source]{.HTML_Keyboard} just by their *id* or *idPattern* (i.e. without specifying their *type*). - -::: {#Table_5.2.8-1 .TH} -Table 5.2.8-1: EntityInfo data type definition -::: - -::: TAL -+-------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+======================+==================================================================================================================================================================================+=============+============================================================================================================+ -| type | String or String[] | Fully Qualified Name of an Entity Type or the Entity Type name as a short-hand string. See [clause 4.6.2](9-tabcontext-information-management-framework.md#tabsupported-names) | 1 | Entity Type (or JSON array, in case of Entities with multiple Entity Types). | -+-------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ -| id | String | Valid URI | 0..1 | Entity identifier. | -+-------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ -| idPattern | String | Regular expression as per IEEE 1003.2™ [[11]](7-tabreferences.md#11) | 0..1 | A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. | -+-------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.9 CSourceRegistration {#tabcsourceregistration number="10.2.9"} - -This type represents the data needed to register a new [Context Source]{.HTML_Keyboard}. - -The supported JSON members shall follow the indications provided in [Table 5.2.9‑1](10-tabapi-operation-definition.md#Table_5.2.9-1). - -::: {#Table_5.2.9-1 .TH} -Table 5.2.9-1: CSourceRegistration data type definition -::: - -::: TAL -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================+===========================================================================================================================+===========================================================================================================================================================================================+=============================================================================================================================================================================================================================================================================================================================================================+===========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| id | String | Valid URI. | 0..1 | Generated at creation time, if it is not provided, it will be assigned during registration process and returned to client. | -| | | | | | -| | | Unique registration identifier. (JSON-LD *\@id*). | | It cannot be later modified in update operations. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["ContextSourceRegistration"]{.HTML_Code} | 1 | JSON-LD *\@type* | -| | | | | | -| | | | | Use reserved type for identifying Context Source Registration. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endpoint | String | It shall be a dereferenceable URI | 1 | Endpoint expressed as dereferenceable URI through which the [Context Source]{.HTML_Keyboard} exposes its NGSI-LD interface. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceInfo | KeyValuePair[] | 0..1 | Generic {key, value} array to convey optional information to provide when contacting the registered [Context Source.]{.HTML_Keyboard} | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| information | RegistrationInfo[] | See data type definition in [clause 5.2.10](10-tabapi-operation-definition.md#tabregistrationinfo). Empty array (0 length) is not allowed | 1 | Describes the Entities, Properties and Relationships for which the [Context Source]{.HTML_Keyboard} may be able to provide information. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceAlias | String | Non-empty string. Pseudonym field as defined in IETF RFC 7230 [[27]](7-tabreferences.md#27) | 0..1 | A previously retrieved unique id for a registered [Context Source]{.HTML_Keyboard} which is used to identify loops. | -| | | | | | -| | | | | In the multi-tenancy use case (see [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)), this id shall be used to **identify** a specific [Tenant]{.HTML_Keyboard} within a registered [Context Source]{.HTML_Keyboard}. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| description | String | Non-empty string | 0..1 | A description of this [Context Source Registration.]{.HTML_Keyboard} | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String[] | Valid URIs,["@none"]{.HTML_Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of Attributes that the [Context Source]{.HTML_Keyboard} can provide, defined as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Provides an expiration date. When passed the [Context Source Registration]{.HTML_Keyboard} will become invalid and the [Context Source]{.HTML_Keyboard} might no longer be available. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| location | GeoJSON Geometry as mandated by [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 0..1 | Location for which the [Context Source]{.HTML_Keyboard}may be able to provide information. | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| management | Registration | See data type definition in [clause 5.2.34](10-tabapi-operation-definition.md#tabregistrationmanagementinfo) | 0..1 | Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. | -| | | | | | -| | Management | | | | -| | | | | | -| | Info | | | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| managementInterval | TimeInterval | See data type definition in [clause 5.2.11](10-tabapi-operation-definition.md#tabtimeinterval) | 0..1 | If present, the [Context Source]{.HTML_Keyboard} can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The *managementInterval* specifies the time interval for which the [Context Source]{.HTML_Keyboard} can provide Entity information as specified by the *createdAt*, *modifiedAt* and *deletedAt* Temporal Properties. A temporal query based on the *createdAt*, *modifiedAt* or *deletedAt* Temporal Property is matched against the *managementInterval* for overlap. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| mode | String | It shall be one of: | 0..1 | The definition of the mode of distributed operation (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)) supported by the registered [Context Source.]{.HTML_Keyboard} | -| | | | | | -| | | ["inclusive","exclusive","redirect"]{.HTML_Code} or ["auxiliary"]{.HTML_Code} | | | -| | | | | | -| | | The mode is assumed to be ["inclusive"]{.HTML_Code} if not explicitly defined | | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observationInterval | TimeInterval | See data type definition in [clause 5.2.11](10-tabapi-operation-definition.md#tabtimeinterval) | 0..1 | If present, the [Context Source]{.HTML_Keyboard} can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The *observationInterval* specifies the time interval for which the [Context Source]{.HTML_Keyboard} can provide Entity information as specified by the *observedAt* Temporal Property. A temporal query based on the *observedAt* Temporal Property, which is the default, is matched against the *observationInterval* for overlap. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observationSpace | GeoJSON Geometry as mandated by [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 0..1 | Geographic location that includes the observation spaces of all entities as specified by their respective *observationSpace* *GeoProperty* for which the [Context Source]{.HTML_Keyboard} may be able to provide information. | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| operations | String[] | Entries are limited to the named API operations and named operation groups (see [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)) | 0..1 | The definition limited subset of API operations supported by the registered [Context Source.]{.HTML_Keyboard} | -| | | | | | -| | | | | If undefined, the default set of operations is ["federationOps"]{.HTML_Code} (see [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)). | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| operationSpace | GeoJSON Geometry as mandated by [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 0..1 | Geographic location that includes the operation spaces of all entities as specified by their respective *operationSpace* *GeoProperty* for which the [Context Source]{.HTML_Keyboard} may be able to provide information. | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| refreshRate | String | String representing a duration in ISO 8601 [[17]](7-tabreferences.md#17) format | 0..1 | An indication of the likely period of time to elapse between updates at this registered endpoint. | -| | | | | | -| | | | | Brokers may optionally use this information to help implement caching. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| registrationName | String | Non-empty string | 0..1 | A name given to this [Context Source Registration]{.HTML_Keyboard}. | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scope | String or | Scope(s) | 0..1 | Scopes (see [clause 4.18](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes)) for which the [Context Source]{.HTML_Keyboard} has Entities. | -| | | | | | -| | String[] | | | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| tenant | String | 0..1 | Identifies the [Tenant]{.HTML_Keyboard} that has to be specified in all requests to the [Context Source]{.HTML_Keyboard} that are related to the information registered in this [Context Source Registration]{.HTML_Keyboard}. If not present, the default [Tenant]{.HTML_Keyboard} is assumed. Should only be present in systems supporting multi-tenancy. | | -+---------------------+---------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The members (defined by Table 5.2.9-2) of the *CSourceRegistration* data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.9-2 .TH} -Table 5.2.9-2: Additional members of the CSourceRegistration data type -::: - -::: TAL -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===================================================+=======================================+========================================================================================+=====================================+===========================================================================================================================================================================================================================================================================================================+ -| [lastFailure]{.ondemand_CHAR_size_9_color_000000} | [String]{.ondemand_CHAR_color_000000} | *DateTime*[(clause ]{.ondemand_CHAR_color_000000}4.6.3[)]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Timestamp corresponding to the instant when]{.ondemand_CHAR_size_9_color_000000}[the last distributed operation resulting in a failure (for]{.ondemand_CHAR_size_9_color_000000}[instance, in the HTTP binding, an HTTP response code other than 2xx) was returned.]{.ondemand_CHAR_size_9_color_000000} | -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| status | String | Allowed values: | 0..1 | Read-only., Status of the Registration. It shall be ["ok"]{.HTML_Code} if the last attempt to perform a distributed operation succeeded. It shall be ["failed"]{.HTML_Code} if the last attempt to perform a distributed operation failed. | -| | | | | | -| | | ["ok"]{.HTML_Code} | | | -| | | | | | -| | | ["failed"]{.HTML_Code} | | | -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [timesFailed]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [0 or greater value]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Number of times that the registration triggered a distributed operation request that failed.]{.ondemand_CHAR_color_000000} | -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [timesSent]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [0 or greater value]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Number of times that the registration triggered a distributed operation, including failed attempts.]{.ondemand_CHAR_color_000000} | -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [lastSuccess]{.ondemand_CHAR_color_000000} | [String]{.ondemand_CHAR_color_000000} | *DateTime*[(clause ]{.ondemand_CHAR_color_000000}4.6.3[)]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Timestamp corresponding to the instant when the last successfully distributed operation was sent. Created on first successful operation.]{.ondemand_CHAR_color_000000} | -+---------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------+-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.10 RegistrationInfo {#tabregistrationinfo number="10.2.10"} - -The supported JSON members shall follow the requirements provided in [Table 5.2.10‑1](10-tabapi-operation-definition.md#Table_5.2.10-1). - -::: {#Table_5.2.10-1 .TH} -Table 5.2.10-1: RegistrationInfo data type definition -::: - -::: TAL -+-------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===================+================+==================================================================================================================================================================================================================================================================+=============+==================================================================================+ -| entities | EntityInfo[] | See data type definition in [clause 5.2.8](10-tabapi-operation-definition.md#tabentityinfo). Empty array (0 length) is not allowed. Restrictions in [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations) apply as well | 0..1 | Describes the entities for which the CSource may be able to provide information. | -+-------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ -| propertyNames | String[] | Property names as short hand strings or URIs. Empty array is not allowed. Restrictions in [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations) apply as well | 0..1 | Describes the Properties that the CSource may be able to provide. | -+-------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ -| relationshipNames | String[] | Relationship names as short hand strings or URIs. Empty array is not allowed. Restrictions in [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations) apply as well | 0..1 | Describes the Relationships that the CSource may be able to provide. | -+-------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------+ -::: - -At least one element of *RegistrationInfo* shall be present. - -### 5.2.11 TimeInterval {#tabtimeinterval number="10.2.11"} - -The supported JSON members shall follow the requirements provided in [Table 5.2.11‑1](10-tabapi-operation-definition.md#Table_5.2.11-1). - -::: {#Table_5.2.11-1 .TH} -Table 5.2.11-1: TimeInterval data type definition -::: - -::: TAL -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=============+====================================================================================================================+=============+=============================================================================+ -| startAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Describes the start of the time interval | -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------+ -| endAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Describes the end of the time interval. If not present the interval is open | -+-------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------+ -::: - -### 5.2.12 Subscription {#tabsubscription number="10.2.12"} - -This datatype represents a Context Subscription. - -The supported JSON members shall follow the requirements provided in [Table 5.2.12‑1](10-tabapi-operation-definition.md#Table_5.2.12-1). - -::: {#Table_5.2.12-1 .TH} -Table 5.2.12-1: Subscription data type definition -::: - -::: TAL -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=====================+====================+===================================================================================================================================================================================================================================================================================================================================================+=============+========================================================================================================================================================================================================================+========================================================================================================================================================================================================================================================================================================================================================================================================+ -| id | String | Valid URI | 0..1 | Subscription identifier (JSON-LD *\@id*). Generated at creation time, if it is not provided, it will be assigned during subscription process and returned to client. | -| | | | | | -| | | | | It cannot be later modified in update operations. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["Subscription"]{.HTML_Code} | 1 | JSON-LD *\@type.* | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entities | EntitySelector[] | See data type definition in [clause 5.2.33](10-tabapi-operation-definition.md#tabentityselector). Empty array (0 length) is not allowed. | 0..1 | Entities subscribed. | -| | | | | | -| | | Mandatory if *timeInterval* is present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)) | | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| notification | NotificationParams | See data type definition in [clause 5.2.14](10-tabapi-operation-definition.md#tabnotificationparams) | 1 | Notification details. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| notificationTrigger | String[] | Valid notification triggers are ["entityCreated"]{.HTML_Code}[, ]{.Plain_Text_Char}["entityUpdated"]{.HTML_Code}[, ]{.Plain_Text_Char}["entityDeleted"]{.HTML_Code}[, ]{.Plain_Text_Char}["attributeCreated"]{.HTML_Code}[, ]{.Plain_Text_Char}["attributeUpdated"]{.HTML_Code}[, ]{.Plain_Text_Char}["attributeDeleted"]{.HTML_Code} | 0..1 | The notification triggers listed indicate what kind of changes shall trigger a notification. If not present, the default is the combination ["attributeCreated"]{.HTML_Code} and ["attributeUpdated"]{.HTML_Code}. ["entityUpdated"]{.HTML_Code} is equivalent to the combination ["attributeCreated"]{.HTML_Code}, ["attributeUpdated"]{.HTML_Code} and ["attributeDeleted"]{.HTML_Code}. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| watchedAttributes | String[] | Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed. | 0..1 | Watched Attributes (Properties or Relationships). If not defined it means any Attribute. | -| | | | | | -| | | if *timeInterval* is present it shall not appear (0 cardinality) | | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | A valid query string as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) | 0..1 | Query that shall be met by subscribed entities in order to trigger the notification. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoQ | GeoQuery | See data type definition in [clause 5.2.13](10-tabapi-operation-definition.md#tabgeoquery) | 0..1 | Geoquery that shall be met by subscribed entities in order to trigger the notification. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | See [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) | 0..1 | Scope query. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| temporalQ | TemporalQuery | See data type definition in [clause 5.2.21](10-tabapi-operation-definition.md#tabtemporalquery) | 0..1 | Temporal Query to be used **only** in *Context Registration Subscriptions* for matching [Context Source Registrations]{.HTML_Keyboard} of [Context Sources]{.HTML_Keyboard} providing temporal information. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | A valid query string as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) | 0..1 | Context source filter that shall be met by [Context Source Registrations]{.HTML_Keyboard} describing [Context Sources]{.HTML_Keyboard} to be used for Entity Subscriptions. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String[] | Valid URIs,["@none"]{.HTML_Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| description | String | 0..1 | Subscription description. | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expandValues | String | Comma separated list of attribute names | 0..1 | Values of the identified attributes should be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Expiration date for the subscription. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| isActive | Boolean | *true* by default | 0..1 | Allows clients to temporarily pause the subscription by making it inactive. *true* indicates that the Subscription is under operation. *false* indicates that the subscription is paused, and notifications shall not be delivered. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| jsonKeys | String | Comma separate list of attribute names | 0..1 | Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| jsonldContext | String | Dereferenceable URI | 0..1 | The dereferenceable URI of the JSON-LD *\@context* to be used when sending a notification resulting from the subscription. If not provided, the *\@context* used for the subscription shall be used as a default. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | A natural language filter in the form of a IETF RFC 5646 [[28]](7-tabreferences.md#28) language code | 0..1 | Language filter to be applied to the query [(clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter)). | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| localOnly | Boolean | 0..1 | If *localOnly=true* then the subscription only pertains to the Entities stored locally. In case the Subscription pertains to a Snapshot it is always local, regardless of whether *localOnly* is set to *true* or not. | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildConformance | String | A semantically versioned string in the form *major.minor*, which conforms to a version of the NGSI-LD specification | 0..1 | If provided the notification shall undergo a backwards compatibility operation as defined by [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads) and be amended to conform to the supplied version of the NGSI-LD specification. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| splitEntities | Boolean | default decided by implementation; it should be configurable. The parameter does not apply in case *localOnly* is *true*. | 0..1 | If *true* it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If *false* it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| subscriptionName | String | 0..1 | A (short) name given to this Subscription. | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| throttling | Number | Greater than 0. Fractional values are allowed. If *timeInterval* is present it shall not appear (0 cardinality) | 0..1 | Minimal period of time in seconds which shall elapse between two consecutive notifications. | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeInterval | Number | Greater than 0 | 0..1 | Indicates that a notification shall be delivered periodically regardless of attribute changes. Actually, when the time interval (in seconds) specified in this value field is reached. | -| | | | | | -| | | if *watchedAttributes* is present it shall not appear (0 cardinality) | | | -+---------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -At least one of (a) *entities* or (b) *watchedAttributes* shall be present, unless the member [localOnly ]{.HTML_Code}is set to *true,* in which case the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). - -The members (defined by Table 5.2.12-2) of the *Subscription* data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.12-2 .TH} -Table 5.2.12-2: Additional members of the Subscription data type -::: - -::: TAL -+-------------+-------------+---------------------------+-------------+--------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=============+===========================+=============+================================================================================+ -| status | String | Allowed values: | 0..1 | Read-only. Provided by the system when querying the details of a subscription. | -| | | | | | -| | | ["active"]{.HTML_Code} | | | -| | | | | | -| | | ["paused"]{.HTML_Code} | | | -| | | | | | -| | | ["expired"]{.HTML_Code} | | | -+-------------+-------------+---------------------------+-------------+--------------------------------------------------------------------------------+ -::: - -### 5.2.13 GeoQuery {#tabgeoquery number="10.2.13"} - -This datatype represents a geoquery used for Subscriptions. - -The supported JSON members shall follow the requirements provided in [Table 5.2.13‑1](10-tabapi-operation-definition.md#Table_5.2.13-1). - -::: {#Table_5.2.13-1 .TH} -Table 5.2.13-1: GeoQuery data type definition -::: - -::: TAL -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+======================+=======================================================================================================================================+=============+======================================================================================================================================================================================================================+ -| coordinates | JSON Array or String | A JSON Array coherent with the geometry type as per IETF RFC 7946 [[8]](7-tabreferences.md#8) | 1 | Coordinates of the reference geometry. For the sake of JSON-LD compatibility It can be encoded as a string as described in [clause 4.7.1](9-tabcontext-information-management-framework.md#tabgeojson-geometries). | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | A valid GeoJSON [[8]](7-tabreferences.md#8) geometry type excepting *GeometryCollection* | 1 | Type of the reference geometry. | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| georel | String | A valid geo-relationship as defined by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) | 1 | Geo-relationship (["near"]{.HTML_Code}, ["within"]{.HTML_Code}, etc.). | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoproperty | String | Attribute name as short hand string or URI | 0..1 | Specifies the GeoProperty to which the GeoQuery is to be applied. If not present, the default GeoProperty is *location*. | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.14 NotificationParams {#tabnotificationparams number="10.2.14"} - -#### 5.2.14.1 NotificationParams data type definition {#tabnotificationparams-data-type-definition number="10.2.14.1"} - -This datatype represents the parameters that allow to convey the details of a notification. - -The supported JSON members shall follow the requirements provided in [Table 5.2.14.1‑1](10-tabapi-operation-definition.md#Table_5.2.14.1-1). - -::: {#Table_5.2.14.1-1 .TH} -Table 5.2.14.1-1: NotificationParams data type definition -::: - -::: TAL -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=============+==============================================================================================================================================================================================================================================================================================================================+=============+=========================================================================================================================================================================================================================================================================================================================================+ -| endpoint | Endpoint | See data type definition in [clause 5.2.15](10-tabapi-operation-definition.md#tabendpoint) | 1 | Notification endpoint details. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| attributes | String[] | Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed | 0..1 | A synonym for *pick*, except that *id, type, scope* are not allowed. **Deprecated** | -| | | | | | -| | | | | Attribute names to be included in the notification payload body. If undefined it will mean all Attributes. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| format | String | It shall be one of: ["normalized"]{.HTML_Code}, ["concise"]{.HTML_Code}[,]{.Plain_Text_Char} ["simplified"]{.HTML_Code} (or its synonym ["keyValues"]{.HTML_Code}[)]{.Plain_Text_Char} | 0..1 | Conveys the representation format of the entities delivered at notification time. By default, it will be in the normalized format. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| join | String | It shall be one of: ["flat"]{.HTML_Code}, ["inline"]{.HTML_Code}, ["@none"]{.HTML_Code} | 0..1 | String representing the type of [Linked Entity]{.HTML_Keyboard} retrieval to apply. | -| | | | | | -| | | | | By default, it will be ["@none"]{.HTML_Code}. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| joinLevel | Number | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML_Keyboard} retrieval to apply. Default is 1. Only applicable if *join* parameter is ["flat"]{.HTML_Code}, or ["inline"]{.HTML_Code}. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | String[] | Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope" ]{.HTML_Code}or a projected Attribute name) as a valid attribute projection language string as per [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language). Empty array (0 length) is not allowed | 0..1 | When defined, the specified Entity members are removed from each Entity within the payload. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | String[] | Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name as a valid attribute projection language string as per [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)). Empty array (0 length) is not allowed | 0..1 | When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| showChanges | Boolean | *false* by default | 0..1 | If *true* the previous *value* (*previousValue)* of Properties or *languageMap* (*previousLanguageMap)* of Language Properties or *object* (*previousObject*) of Relationships is provided in addition to the current one. This requires that it exists, i.e. in case of modifications and deletions, but not in the case of creations. | -| | | | | | -| | | | | *showChanges* cannot be *true* in case format is ["keyValues"]{.HTML_Code}. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| sysAttrs | Boolean | *false* by default | 0..1 | If *true*, the system generated attributes *createdAt* and *modifiedAt* and the system attribute *expiresAt* are included in the response payload body, in the case of a deletion also *deletedAt*. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 5.2.14.2 Output only members {#taboutput-only-members number="10.2.14.2"} - -The following **output only** members (defined by Table 5.2.14.2-1) of the *NotificationParams* data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by *Context Subscribers*. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -In query or retrieve operations involving Subscriptions, implementations shall generate them as part of their representation. - -::: {#Table_5.2.14.2-1 .TH} -Table 5.2.14.2-1: Output only members of the NotificationParams data structure -::: - -::: TAL -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+============================================+=============+====================================================================================================================+=============+=========================================================================================================================================================================================================================================================+ -| lastFailure | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp corresponding to the instant when the last notification resulting in failure (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. Provided by the system when querying the details of a subscription. | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastNotification | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp corresponding to the instant when the last notification has been sent. Provided by the system when querying the details of a subscription. | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastSuccess | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp corresponding to the instant when the last successful (200 OK response) notification has been sent. Provided by the system when querying the details of a subscription. | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| status | String | Allowed values: | 0..1 | Status of the Notification. It shall be ["ok"]{.HTML_Code} if the last attempt to notify the subscriber succeeded. It shall be ["failed"]{.HTML_Code} if the last attempt to notify the subscriber failed. | -| | | | | | -| | | ["ok"]{.HTML_Code}, ["failed"]{.HTML_Code} | | | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [timesFailed]{.ondemand_CHAR_color_000000} | Number | Greater than 0 | 0..1 | Number of times an unsuccessful response (or timeout) has been received when delivering the notification. Provided by the system when querying the details of a subscription. | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timesSent | Number | Greater than 0 | 0..1 | Number of times that the notification has been sent. Provided by the system when querying the details of a subscription. | -+--------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.15 Endpoint {#tabendpoint number="10.2.15"} - -This datatype represents the parameters that are required in order to define an endpoint for notifications. This can include, in addition the endpoint's URI, a generic{key, value} array, named *receiverInfo*, which contains, in a generalized form, whatever extra information the [Context Broker]{.HTML_Keyboard} shall convey to the receiver in order for the [Context Broker]{.HTML_Keyboard} to successfully communicate with receiver (e.g. Authorization material), or for the receiver to correctly interpret the received content (e.g. the Link URL to fetch an *\@context*). Additionally, it can include another generic{key, value} array, named *notifierInfo*, which contains the configuration that the [Context Broker]{.HTML_Keyboard} needs to know in order to correctly set up the communication channel towards the receiver (e.g. MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in [clause 7.2](12-tabapi-mqtt-notification-binding.md#tabnotification-behaviour-3)). - -The supported JSON members shall follow the indications provided in [Table 5.2.15‑1](10-tabapi-operation-definition.md#Table_5.2.15-1). - -::: {#Table_5.2.15-1 .TH} -Table 5.2.15-1: Endpoint data type definition -::: - -::: TAL -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=========================================+=======================================+===============================================+============================================================================+================================================================================================================================================================================================================================================================================================================+ -| uri | String | Dereferenceable URI | 1 | URI which conveys the endpoint which will receive the notification. | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| accept | String | MIME type. It shall be one of: | 0..1 | Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). If not present, default is ["application/json"]{.HTML_Code}. | -| | | | | | -| | | ["application/json"]{.HTML_Code} | | | -| | | | | | -| | | ["application/ld+json"]{.HTML_Code} | | | -| | | | | | -| | | ["application/geo+json"]{.HTML_Code} | | | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [cooldown]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [Greater than 0]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent.]{.ondemand_CHAR_size_9_color_000000} | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| notifierInfo | KeyValuePair[] | 0..1 | Generic {key, value} array to set up the communication channel. | | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| receiverInfo | KeyValuePair[] | 0..1 | Generic {key, value} array to convey optional information to the receiver. | | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [timeout]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [Greater than 0]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | [Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. The NGSI-LD system can override this value. This only applies if the binding protocol always returns a response.]{.ondemand_CHAR_color_000000} | -+-----------------------------------------+---------------------------------------+-----------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.16 BatchOperationResult {#tabbatchoperationresult number="10.2.16"} - -This datatype represents the result of a batch operation. - -The supported JSON members shall follow the indications provided in [Table 5.2.16‑1](10-tabapi-operation-definition.md#Table_5.2.16-1). - -::: {#Table_5.2.16-1 .TH} -Table 5.2.16-1: BatchOperationResult data type definition -::: - -::: TAL -+-------------+----------------------+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+======================+=====================+=========================================================================+==================================================================================================================================================================+ -| errors | BatchEntityError[] | 1 | One array item per Element in error. Empty Array if no errors happened. | | -+-------------+----------------------+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| success | String[] | Array of valid URIs | 1 | Array of Entity IDs corresponding to the Elements that were successfully treated by the concerned operation. Empty Array if no Element was successfully treated. | -+-------------+----------------------+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.17 BatchEntityError {#tabbatchentityerror number="10.2.17"} - -This datatype represents an error raised (associated to a particular Entity) during the execution of a batch or distributed operation. - -The supported JSON members shall follow the indications provided in [Table 5.2.17‑1](10-tabapi-operation-definition.md#Table_5.2.17-1). - -::: {#Table_5.2.17-1 .TH} -Table 5.2.17-1: BatchEntityError data type definition -::: - -::: TAL -+----------------+----------------------------------------------------------------------+--------------+-----------------------------------+-----------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+================+======================================================================+==============+===================================+=============================================================================+ -| entityId | String | Valid URI | 1 | Entity ID corresponding to the Entity in error. | -+----------------+----------------------------------------------------------------------+--------------+-----------------------------------+-----------------------------------------------------------------------------+ -| error | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | One instance per Entity in error. | | -+----------------+----------------------------------------------------------------------+--------------+-----------------------------------+-----------------------------------------------------------------------------+ -| registrationId | String | Valid URI | 0..1 | Registration Id corresponding to a failed distributed operation (optional). | -+----------------+----------------------------------------------------------------------+--------------+-----------------------------------+-----------------------------------------------------------------------------+ -::: - -### 5.2.18 UpdateResult {#tabupdateresult number="10.2.18"} - -This datatype represents the result of Attribute update (append or update) operations in the NGSI-LD API regardless of whether local or distributed. - -The supported JSON members shall follow the indications provided in [Table 5.2.18‑1](10-tabapi-operation-definition.md#Table_5.2.18-1). - -::: {#Table_5.2.18-1 .TH} -Table 5.2.18-1: UpdateResult data type definition -::: - -::: TAL -+-------------+-----------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=======================+===============================================================================+===============================================================================+=======================================================================================================================================+ -| notUpdated | NotUpdatedDetails[] | See [clause 5.2.19](10-tabapi-operation-definition.md#tabnotupdateddetails) | 1 | List which contains the Attributes (represented by their name) that were not updated, together with the reason for not being updated. | -+-------------+-----------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| updated | String[] | 1 | List of Attributes (represented by their name) that were appended or updated. | | -+-------------+-----------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.19 NotUpdatedDetails {#tabnotupdateddetails number="10.2.19"} - -This datatype represents additional information provided by an implementation when an Attribute update did not happen. See also [clause 5.2.18](10-tabapi-operation-definition.md#tabupdateresult). - -The supported JSON members shall follow the indications provided in [Table 5.2.19‑1](10-tabapi-operation-definition.md#Table_5.2.19-1). - -::: {#Table_5.2.19-1 .TH} -Table 5.2.19-1: NotUpdatedDetails data type definition -::: - -::: TAL -+----------------+-------------+--------------+-----------------------------------------------+-----------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+================+=============+==============+===============================================+=============================================================================+ -| attributeName | String | 1 | Attribute name. | | -+----------------+-------------+--------------+-----------------------------------------------+-----------------------------------------------------------------------------+ -| reason | String | 1 | Reason for not having changed such Attribute. | | -+----------------+-------------+--------------+-----------------------------------------------+-----------------------------------------------------------------------------+ -| registrationId | String | Valid URI | 0..1 | Registration Id corresponding to a failed distributed operation (optional). | -+----------------+-------------+--------------+-----------------------------------------------+-----------------------------------------------------------------------------+ -::: - -### 5.2.20 EntityTemporal {#tabentitytemporal number="10.2.20"} - -This datatype represents the [Temporal Evolution of an Entity.]{.HTML_Keyboard} - -This is the same datatype as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) with the only deviation that the representation of Properties and Relationships shall be the temporal one, as defined in clauses [4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property) and [4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). Alternatively it is possible to specify the EntityTemporal by using the "Simplified temporal representation of an Entity", as defined in [clause 4.5.9](9-tabcontext-information-management-framework.md#tabsimplified-temporal-representation-of-an-entity). - -### 5.2.21 TemporalQuery {#tabtemporalquery number="10.2.21"} - -This datatype represents a temporal query. - -The supported JSON members shall follow the requirements provided in [Table 5.2.21‑1](10-tabapi-operation-definition.md#Table_5.2.21-1). - -::: {#Table_5.2.21-1 .TH} -Table 5.2.21-1: TemporalQuery data type definition -::: - -::: TAL -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+====================+==================================================================================================================================================================+=======================================================================================================================================================================================================================================================================================================+===================================================================================================================================================================================================================================================================================================================================================================+==============================================================================================================================================================================================================================================================================================+ -| timeAt | String representing the *timeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language) | It shall be a *DateTime* | 1 | | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timerel | String | Allowed values: ["before"]{.HTML_Code}[,]{.Plain_Text_Char} ["after"]{.HTML_Code} and ["between"]{.HTML_Code} | 1 | Represents the temporal relationship as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| aggrMethods | Comma separated list of string | It shall be 1 if *aggregatedValues* is present in the *options* parameter | 0..1 | Each String represents an aggregation method, as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). Only applicable if ["aggregatedValues"]{.HTML_Code} is present in the *format* or *options* parameter. | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| aggrPeriodDuration | String | 0..1 | It represents the duration of each period used for the aggregation as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. | | -| | | | | | -| | | | Only applicable if ["aggregatedValues"]{.HTML_Code}is present in the *format* *or* *options* parameter. | | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endTimeAt | String representing the *endTimeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language) | It shall be a *DateTime.* Cardinality shall be 1 if *timerel* is equal to ["between"]{.HTML_Code} | 0..1 | | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastN | Positive integer | 0..1 | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. | | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeproperty | String representing a Temporal Property name | Allowed values: ["observedAt"]{.HTML_Code}, ["createdAt"]{.HTML_Code}, ["modifiedAt" ]{.HTML_Code}and ["deletedAt"]{.HTML_Code}. If not specified, the default is ["observedAt"]{.HTML_Code}. (See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)) | 0..1 | | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.22 KeyValuePair {#tabkeyvaluepair number="10.2.22"} - -This datatype represents the optional information that is required when contacting an endpoint for notifications. - -The supported members shall follow the indications provided in [Table 5.2.22‑1](10-tabapi-operation-definition.md#Table_5.2.22-1). They are intended to represent a key/value pair. - -Example optional information includes additional HTTP Headers such as: - -::: B1plus -- The HTTP Authentication Header. -- The HTTP Prefer Header (IETF RFC 7240 [[26]](7-tabreferences.md#26)) used when notifying the GeoJSON Endpoint. -::: - -::: {#Table_5.2.22-1 .TH} -Table 5.2.22-1: KeyValuePair data type definition -::: - -::: TAL -+-------------+-------------+-------------------+-------------+----------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=============+===================+=============+==================================+ -| key | String | Binding-dependent | 1 | The key of the key/value pair. | -+-------------+-------------+-------------------+-------------+----------------------------------+ -| value | String | Binding-dependent | 1 | The value of the key/value pair. | -+-------------+-------------+-------------------+-------------+----------------------------------+ -::: - -### 5.2.23 Query {#tabquery number="10.2.23"} - -This datatype represents the information that is required in order to convey a query when a "Query Entities" operation or a "Query Temporal Evolution of Entities" operation is to be performed (as per clauses [5.7.2](10-tabapi-operation-definition.md#tabquery-entities) and [5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities), respectively). - -The supported JSON members shall follow the requirements provided in [Table 5.2.23‑1](10-tabapi-operation-definition.md#Table_5.2.23-1). - -::: {#Table_5.2.23-1 .TH} -Table 5.2.23-1: Query data type definition -::: - -::: TAL -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===================+====================+==============================================================================================================================================================================================================================================================================================================================+=============================================================================================+=============================================================================================================================================================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["Query"]{.HTML_Code} | 1 | JSON-LD *\@type* | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entities | EntitySelector[] | See data type definition in [clause 5.2.33](10-tabapi-operation-definition.md#tabentityselector). Empty array (0 length) is not allowed | 0..1 | Entity IDs, id pattern and Entity types that shall be matched by Entities in order to be retrieved. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | A valid query string as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) | 0..1 | Query that shall be matched by Entities in order to be retrieved. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoQ | GeoQuery | See data type definition in [clause 5.2.13](10-tabapi-operation-definition.md#tabgeoquery) | 0..1 | Geoquery that shall be matched by Entities in order be retrieved. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | See [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) | 0..1 | Scope query. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| temporalQ | TemporalQuery | See data type definition in [clause 5.2.21](10-tabapi-operation-definition.md#tabtemporalquery) | 0..1 | Temporal Query to be present only for "Query [Temporal Evolution of Entities]{.HTML_Keyboard}" operation [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)). | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| attrs | String[] | Attribute name as short hand strings or URIs. | 0..1 | A synonym for a combination of the *pick* and*q* members. **Deprecated** | -| | | | | | -| | | Empty array (0 length) is not allowed | | List of Attributes that shall be matched by Entities in order to be retrieved. If not present all Attributes will be retrieved. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | String[] | Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name) as a valid attribute projection language string as per [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language). Empty array (0 length) is not allowed | 0..1 | When defined, the specified Entity members are removed from each Entity within the payload. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | String[] | Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name) as a valid attribute projection language string as per [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language). Empty array (0 length) is not allowed | 0..1 | When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| aggrParams | AggregationParams | See data type definition in [clause 5.2.44](10-tabapi-operation-definition.md#tabaggregationparams). | 0..1 | Aggregation parameters required for supporting aggregation methods in to be present only for "[QueryTemporal Evolution of Entities]{.HTML_Keyboard} " operation [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)). | -| | | | | | -| | | | | Only applicable if ["aggregatedValues"]{.HTML_Code} is present in the*format* or *options* parameter. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | A valid query string as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) | 0..1 | Context source filter that shall be matched by [Context Source Registrations]{.HTML_Keyboard} describing [Context Sources]{.HTML_Keyboard} to be used for retrieving Entities. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| containedBy | String[] | Comma separated list of URIs. Empty array (0 length) is not allowed | 0..1 | List of entity ids which have previously been encountered whilst retrieving the Entity Graph. | -| | | | | | -| | | | | Only applicable if *joinLevel* is present. | -| | | | | | -| | | | | Only applicable for the "Retrieve Entity" [(clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)) and "Query Entities" operations [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)). | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String[] | Valid URIs,["@none"]{.HTML_Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expandValues | String | Comma separated list of attribute names | 0..1 | Values of the identified attributes should be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMap | Boolean | 0..1 | If *true*, the location of the EntityMap used in the operation is returned in the response. | | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMapLifetime | String | String representing a duration in ISO 8601 [[17]](7-tabreferences.md#17) format | 0..1 | Suggested duration for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to *true*. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| jsonKeys | String | Comma separate list of attribute names | 0..1 | Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| join | String | It shall be one of: ["flat"]{.HTML_Code}, ["inline"]{.HTML_Code}, ["@none"]{.HTML_Code} | 0..1 | String representing the type of [Linked Entity]{.HTML_Keyboard} retrieval to apply. | -| | | | | | -| | | | | By default, it will be ["@none".]{.HTML_Code} | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| joinLevel | Number | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML_Keyboard} retrieval to apply. Default is 1. Only applicable if *join* parameter is ["flat"]{.HTML_Code}, or ["inline"]{.HTML_Code}. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | A natural language filter in the form of a IETF RFC 5646 [[28]](7-tabreferences.md#28) language code | 0..1 | Language filter to be applied to the query [(clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter)). | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ordering | OrderingParams | See data type definition in [clause 5.2.43](10-tabapi-operation-definition.md#taborderingparams) | 0..1 | When defined, the Entities returned in the payload shall be ordered according to the members defined. | -| | | | | | -| | | | | This only applies if the operation is limited to the local scope. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| splitEntities | Boolean | default decided by implementation; it should be configurable. The parameter does not apply in case the parameter *local* is *true* or the query applies to a Snapshot | 0..1 | If *true* it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If *false* it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. | -+-------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.24 EntityTypeList {#tabentitytypelist number="10.2.24"} - -This type represents the data needed to define the entity type list representation as mandated by [clause 4.5.10](9-tabcontext-information-management-framework.md#tabentity-type-list-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.24‑1](10-tabapi-operation-definition.md#Table_5.2.24-1). - -::: {#Table_5.2.24-1 .TH} -Table 5.2.24-1: NGSI-LD EntityTypeList data type definition -::: - -::: TAL -+-------------+-------------+-------------------------------------------------------+----------------------------------------+----------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=============+=======================================================+========================================+==================================================================================+ -| id | String | Valid URI | 1 | URI that is unique within the system scope. Identifier for the entity type list. | -+-------------+-------------+-------------------------------------------------------+----------------------------------------+----------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["EntityTypeList"]{.HTML_Code} | 1 | JSON-LD *\@type*. | -+-------------+-------------+-------------------------------------------------------+----------------------------------------+----------------------------------------------------------------------------------+ -| typeList | String[] | 1 | List containing the entity type names. | | -+-------------+-------------+-------------------------------------------------------+----------------------------------------+----------------------------------------------------------------------------------+ -::: - -### 5.2.25 EntityType {#tabentitytype number="10.2.25"} - -This type represents the data needed to define the elements of the detailed entity type list representation as mandated by [clause 4.5.11](9-tabcontext-information-management-framework.md#tabdetailed-entity-type-list-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.25‑1](10-tabapi-operation-definition.md#Table_5.2.25-1). - -::: {#Table_5.2.25-1 .TH} -Table 5.2.25-1: NGSI-LD EntityType data type definition -::: - -::: TAL -+----------------+-------------+---------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+================+=============+===================================================+=====================================================================================+================================================================+ -| id | String | Valid URI | 1 | Fully Qualified Name (FQN) of the entity type being described. | -+----------------+-------------+---------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------+ -| type | String | It shall be equal to ["EntityType"]{.HTML_Code} | 1 | JSON-LD *\@type*. | -+----------------+-------------+---------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------+ -| attributeNames | String[] | 1 | List containing the names of attributes that instances of the entity type can have. | | -+----------------+-------------+---------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------+ -| typeName | String | 1 | Name of the entity type, short name if contained in *\@context*. | | -+----------------+-------------+---------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------+ -::: - -### 5.2.26 EntityTypeInfo {#tabentitytypeinfo number="10.2.26"} - -This type represents the data needed to define the detailed entity type information representation as mandated by [clause 4.5.12](9-tabcontext-information-management-framework.md#tabentity-type-information-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.26‑1](10-tabapi-operation-definition.md#Table_5.2.26-1). - -::: {#Table_5.2.26-1 .TH} -Table 5.2.26-1: NGSI-LD EntityTypeInfo data type definition -::: - -::: TAL -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+==================+===============+====================================================================================================================================================================================================================================================+==================================================================+===================================================================================+ -| id | String | Valid URI | 1 | Fully Qualified Name (FQN) of the entity type being described. | -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["EntityTypeInfo"]{.HTML_Code} | 1 | JSON-LD *\@type*. | -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| attributeDetails | Attribute[] | See data type definition in [clause 5.2.28](10-tabapi-operation-definition.md#tabattribute). Attribute with only the elements ["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["attributeName"]{.HTML_Code} and ["attributeTypes"]{.HTML_Code} | 1 | List of attributes that entity instances with the specified entity type can have. | -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| entityCount | Number | Unsigned integer | 1 | Number of entity instances of this entity type. | -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| typeName | String | 1 | Name of the entity type, short name if contained in *\@context*. | | -+------------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------------------------------------------+ -::: - -### 5.2.27 AttributeList {#tabattributelist number="10.2.27"} - -This type represents the data needed to define the attribute list representation as mandated by [clause 4.5.13](9-tabcontext-information-management-framework.md#tabattribute-list-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.27‑1](10-tabapi-operation-definition.md#Table_5.2.27-1). - -::: {#Table_5.2.27-1 .TH} -Table 5.2.27-1: NGSI-LD AttributeList data type definition -::: - -::: TAL -+---------------+-------------+------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+===============+=============+======================================================+======================================+================================================================================+ -| id | String | Valid URI | 1 | URI that is unique within the system scope. Identifier for the attribute list. | -+---------------+-------------+------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["AttributeList"]{.HTML_Code} | 1 | JSON-LD \@type. | -+---------------+-------------+------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------+ -| attributeList | String[] | 1 | List containing the attribute names. | | -+---------------+-------------+------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------+ -::: - -### 5.2.28 Attribute {#tabattribute number="10.2.28"} - -This type represents the data needed to define the attribute information needed as: - -::: B1plus -- part of the entity type information representation as mandated by [clause 4.5.12](9-tabcontext-information-management-framework.md#tabentity-type-information-representation); -- the detailed attribute list representation as mandated by [clause 4.5.14](9-tabcontext-information-management-framework.md#tabdetailed-attribute-list-representation); -- the attribute information representation as mandated by [clause 4.5.15](9-tabcontext-information-management-framework.md#tabattribute-information-representation). -::: - -The supported JSON members shall follow the requirements provided in [Table 5.2.28‑1](10-tabapi-operation-definition.md#Table_5.2.28-1). - -::: {#Table_5.2.28-1 .TH} -Table 5.2.28-1: NGSI-LD Attribute data type definition -::: - -::: TAL -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+================+=============+==================================================+=======================================================================================================================================================+=========================================================+ -| id | String | Valid URI | 1 | Full URI of attribute name. | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| type | String | It shall be equal to ["Attribute"]{.HTML_Code} | 1 | JSON-LD *\@type*. | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| attributeName | String | 1 | Name of the attribute, short name if contained in *\@context*. | | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| attributeCount | Number | Unsigned integer | 0..1 | Number of attribute instances with this attribute name. | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| attributeTypes | String[] | 0..1 | List of attribute types (e.g. *Property*, *Relationship*, *GeoProperty*) for which entity instances exist, which contain an attribute with this name. | | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -| typeNames | String[] | 0..1 | List of entity type names for which entity instances exist containing attributes that have the respective name. | | -+----------------+-------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+ -::: - -### 5.2.29 Feature {#tabfeature number="10.2.29"} - -This data type represents a spatially bounded Entity in GeoJSON format, as mandated by IETF RFC 7946 [[8]](7-tabreferences.md#8). The supported JSON members shall follow the requirements provided in [Table 5.2.29‑1](10-tabapi-operation-definition.md#Table_5.2.29-1). - -::: {#Table_5.2.29-1 .TH} -Table 5.2.29-1: Feature data type definition -::: - -::: TAL -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=================================+=======================================================================================================================================================================================+=============+==========================================================================================================================================================+ -| id | String | Valid URI | 1 | Entity ID. | -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["Feature"]{.HTML_Code} | 1 | GeoJSON Type. | -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | GeoJSON Object | The value field from the matching *GeoProperty* (as specified in [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities)) or *null* | 1 | *null* if no matching *GeoProperty*. | -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| properties | FeatureProperties | See data type definition | 1 | List of attributes as mandated by [clause 5.2.31](10-tabapi-operation-definition.md#tabfeatureproperties). | -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| \@context | URI, JSON Object, or JSON Array | See [[2]](7-tabreferences.md#2), section 5.1. | 0..1 | JSON-LD *\@context*. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [[26]](7-tabreferences.md#26)). | -+-------------+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.30 FeatureCollection {#tabfeaturecollection number="10.2.30"} - -This data type represents a list of spatially bounded Entities in GeoJSON format, as mandated by IETF RFC 7946 [[8]](7-tabreferences.md#8). The supported JSON members shall follow the requirements provided in [Table 5.2.30‑1](10-tabapi-operation-definition.md#Table_5.2.30-1). - -::: {#Table_5.2.30-1 .TH} -Table 5.2.30-1: FeatureCollection data type definition -::: - -::: TAL -+-------------+---------------------------------+----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=================================+==========================================================+=============+==========================================================================================================================================================+ -| type | String | It shall be equal to ["FeatureCollection"]{.HTML_Code} | 1 | GeoJSON Type. | -+-------------+---------------------------------+----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| features | Feature[] | See data type definition | 1..N | In the case that no matches are found, *features* will be an empty array. | -+-------------+---------------------------------+----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| \@context | URI, JSON Object, or JSON Array | See [[2]](7-tabreferences.md#2), section 5.1. | 0..1 | JSON-LD *\@context*. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [[26]](7-tabreferences.md#26)). | -+-------------+---------------------------------+----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.31 FeatureProperties {#tabfeatureproperties number="10.2.31"} - -This data type represents the type and the associated attributes (*Properties* and *Relationships*) of an Entity in GeoJSON format. - -::: {#Table_5.2.31-1 .TH} -Table 5.2.31-1: FeatureProperties data type definition -::: - -::: TAL -+-------------------------------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+======================================================+======================================================================================================+=====================================+====================================================================================================================================================================+ -| type | String or String[] | Entity Type | 1 | Entity Type (or JSON array, in case of Entities with multiple Entity Types). Both short hand string (type name) or URI are allowed. | -+-------------------------------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[], see note 1 | See data type definition in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Property as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty or GeoProperty[], see note 1 | See datatype definition in [clause  5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperty]{.HTML_Keyboard} as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[], see note 1 | See datatype definition in [clause  5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperty]{.HTML_Keyboard} as mandated by [clause 4.5.18](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] see note 1 | See datatype definition in [clause  5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} as mandated by [clause 4.5.24](9-tabcontext-information-management-framework.md#tabngsi-ld-jsonproperty-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[]^,^ see note 1 | See datatype definition in [clause  5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperty]{.HTML_Keyboard} as mandated by [clause 4.5.20](9-tabcontext-information-management-framework.md#tabngsi-ld-vocabproperty-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListProperty or ListProperty[], see note 1 | See datatype definition in [clause  5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperty]{.HTML_Keyboard} as mandated by [clause 4.5.21](9-tabcontext-information-management-framework.md#tabngsi-ld-listproperty-representations). | -+-------------------------------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[], see note 2 | See data type definition in [clause  5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationship as mandated by [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). | -| +------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[], see note 2 | See datatype definition in [clause  5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationship]{.HTML_Keyboard} as mandated by [clause 4.5.22](9-tabcontext-information-management-framework.md#tabngsi-ld-listrelationship-representations). | -+-------------------------------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.32 LanguageProperty {#tablanguageproperty number="10.2.32"} - -This type represents the data needed to define a *LanguageProperty* as mandated by [clause 4.5.18](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations). Note that in case of concise representation, the *type* can be omitted (see [clause 4.5.18.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-languageproperty)). - -The supported JSON members shall follow the requirements provided in [Table 5.2.32‑1](10-tabapi-operation-definition.md#Table_5.2.32-1). - -::: {#Table_5.2.32-1 .TH} -Table 5.2.32-1: NGSI-LD LanguageProperty data type definition -::: - -::: TAL -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=======================================+=======================================================+==============================================================================================================================================================================================================================================================================================+=======================================+=============================================================================================================================================================================================================================================+ -| type | string | It shall be equal to ["LanguageProperty"]{.HTML_Code} | 1 | Node type. | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| languageMap | JSON object | A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [[28]](7-tabreferences.md#28) language codes and whose values shall be JSON strings or arrays of JSON strings | 1 | String Property Values defined in multiple natural languages. | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [LanguageProperty]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the [LanguageProperty]{.HTML_Keyboard} guaranteeing its integrity. | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | It shall be equal to ["langString"]{.HTML_Code} (see note 1) | 0..1 | The native JSON-LD *\@type* for the *languageMap* attribute. It shall align with the RDF datatype [[34]](7-tabreferences.md#34). | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 2) | See datatype definition in clauses [5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the [LanguageProperty]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperties]{.HTML_Keyboard} of the [LanguageProperty.]{.HTML_Keyboard} | -| | | | | | -| | or GeoProperty[] (see note 2) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 2) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperties]{.HTML_Keyboard} of the [LanguageProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 2) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} of the [LanguageProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 2) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperties]{.HTML_Keyboard} of the [LanguageProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListProperty | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperties]{.HTML_Keyboard} of the [LanguageProperty]{.HTML_Keyboard}. | -| | | | | | -| | or ListProperty[] (see note 2) | | | | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the [LanguageProperty]{.HTML_Keyboard}. | -| | | | | | -| | or Relationship[] (see note 3) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 3) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationships]{.HTML_Keyboard} of the [LanguageProperty.]{.HTML_Keyboard} | -+---------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| The assigned *\@type* for language tagged strings is datatype URI: [http://www.w3.org/1999/02/22-rdf-syntax-ns#langString]{.HTML_Code} [[34]](7-tabreferences.md#34). | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 3: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.32-2) of the *LanguageProperty* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.32-2 .TH} -Table 5.2.32-2: Output only members of the NGSI-LD LanguageProperty data type -::: - -::: TAL -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=====================+=============+==========================================================================================================================================================================+=============+==================================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of LanguageProperties | 0..1 | URI uniquely identifying a LanguageProperty instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousLanguageMap | JSON object | A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [[28]](7-tabreferences.md#28) language codes and whose values shall be JSON strings. | 0..1 | Previous Language Property's *languageMap.* | -| | | | | | -| | | Only used in Notifications, if the *showChanges* option is explicitly requested | | | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.33 EntitySelector {#tabentityselector number="10.2.33"} - -This type selects which entity or group of entities are queried or subscribed to by [Context Consumers]{.HTML_Keyboard}. Entities can be specified by their id, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [[11]](7-tabreferences.md#11)). - -The JSON members shall follow the indications provided in [Table 5.2.33‑1](10-tabapi-operation-definition.md#Table_5.2.33-1). *id* takes precedence over *idPattern*. - -::: {#Table_5.2.33-1 .TH} -Table 5.2.33-1: EntitySelector data type definition -::: - -::: TAL -+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+======================+=======================================================================================================================================================================================================================================================================+=============+======================================================================================================================================================================================================================================================================================================+ -| type | String | A valid type selection string as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). To indicate a request for all Entities (with implied local scope), ["\*"]{.HTML_Code} is also allowed as a value. | 1 | Selector of Entity Type(s); If type is specified as ["\*"]{.HTML_Code}, implying local scope, local scope shall not be explicitly set to be *false* [(clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)) for the execution of the corresponding operation. | -+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id | String or String[] | Valid URI(s) | 0..1 | Entity identifier(s). | -+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| idPattern | String | Regular expression as per IEEE 1003.2™ [[11]](7-tabreferences.md#11) | 0..1 | A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. | -+-------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.34 RegistrationManagementInfo {#tabregistrationmanagementinfo number="10.2.34"} - -This type represents the data to alter the default behaviour of a [Context Broker]{.HTML_Keyboard} when making a distributed operation request to a registered [Context Source]{.HTML_Keyboard}. The supported JSON members shall follow the indications provided in Table 5.2.34-1. Brokers may override these recommendations. - -::: {#Table_5.2.34-1 .TH} -Table 5.2.34-1: RegistrationManagementInfo data type definition -::: - -::: TAL -+----------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+==============================================+=======================================+=====================================================================================+================================================================================================================================================================================+================================================================================================================================================================================================================================================================+ -| [cacheDuration]{.ondemand_CHAR_color_000000} | [String]{.ondemand_CHAR_color_000000} | String representing a duration in ISO 8601 [[17]](7-tabreferences.md#17) format | [0..1]{.ondemand_CHAR_color_000000} | Minimal period of time which shall elapse between two consecutive context information consumption operations (as defined in [clause 5.7](10-tabapi-operation-definition.md#tabcontext-information-consumption)) related to the same context data will occur. | -| | | | | | -| | | | | If the *cacheDuration* latency period has not been reached, a cached value for the entity or its attributes shall be returned where available. | -+----------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [cooldown]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [Greater than 0]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | Minimum period of time in milliseconds which shall elapse before attempting to make a subsequent forwarded request to the same endpoint after failure. | -| | | | | | -| | | | | If requests are received before the cooldown period has expired, a timeout error response for the registration is automatically returned. | -+----------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| localOnly | Boolean | 0..1 | If *localOnly=true* then distributed operations associated to this [Context Source Registration]{.HTML_Keyboard} will act only on data held directly by the registered Context | | -| | | | | | -| | | | Source itself (see [clause 4.3.6.4](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations)). | | -+----------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [timeout]{.ondemand_CHAR_color_000000} | [Number]{.ondemand_CHAR_color_000000} | [Greater than 0]{.ondemand_CHAR_color_000000} | [0..1]{.ondemand_CHAR_color_000000} | Maximum period of time in milliseconds which may elapse before a forwarded request is assumed to have failed. | -+----------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.35 VocabProperty {#tabvocabproperty number="10.2.35"} - -This type represents the data needed to define a [VocabProperty]{.HTML_Keyboard} as mandated by [clause 4.5.20](9-tabcontext-information-management-framework.md#tabngsi-ld-vocabproperty-representations). In case of concise representation, the *type* can be omitted (see [clause 4.5.20.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-vocabproperty)). - -The supported JSON members shall follow the requirements provided in [Table 5.2.35‑1](10-tabapi-operation-definition.md#Table_5.2.35-1). - -::: {#Table_5.2.35-1 .TH} -Table 5.2.35-1: NGSI-LD VocabProperty data type definition -::: - -::: TAL -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+=======================================================+==============================================================================================================================================================================================================================================================================================+===============================================================================================================================================+==========================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["VocabProperty"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| vocab | String or string[] | 1 | String Values which shall be type coerced to URIs based on the supplied *\@context.* | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [VocabProperty]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the [VocabProperty]{.HTML_Keyboard} guaranteeing its integrity. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | 0..1 | The native JSON-LD *\@type* for the *vocab* attribute. A String Value which shall be type coerced to a URI based on the supplied *\@context*. | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property | See datatype definitions in clauses [5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the [VocabProperty.]{.HTML_Keyboard} | -| | | | | | -| | or Property[] (see note 1) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperties]{.HTML_Keyboard} of the [VocabProperty]{.HTML_Keyboard}. | -| | | | | | -| | or GeoProperty[] (see note 1) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperties]{.HTML_Keyboard} of the [VocabProperty]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} of the [VocabProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperties]{.HTML_Keyboard} of the [VocabProperty]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListProperty]{.HTML_Definition} | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperties]{.HTML_Keyboard} of the [VocabProperty]{.HTML_Keyboard}. | -| | | | | | -| | or [ListProperty]{.HTML_Definition}[] (see note 1) | | | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the [VocabProperty]{.HTML_Keyboard}. | -| | | | | | -| | or Relationship[] (see note 2) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationships]{.HTML_Keyboard} of the [VocabProperty]{.HTML_Keyboard}. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.35-2) of the [VocabProperty]{.HTML_Keyboard} data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by *Context Producers*. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.35-2 .TH} -Table 5.2.35-2: Output only members of the NGSI-LD VocabProperty data type -::: - -::: TAL -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | Data Type | Restrictions | Cardinality | Description | -+===============+======================+====================================================================================================================+=============+===============================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of VocabProperties | 0..1 | URI uniquely identifying a VocabProperty instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousVocab | String or String[] | Only used in Notifications | 0..1 | Previous *VocabProperty's* *vocab.* | -+---------------+----------------------+--------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.36 ListProperty {#tablistproperty number="10.2.36"} - -This type represents the data needed to define a *ListProperty* as mandated by [clause 4.5.21](9-tabcontext-information-management-framework.md#tabngsi-ld-listproperty-representations). Note that in case of concise representation, the *type* can be omitted (see [clause 4.5.21.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listproperty)). - -The supported JSON members shall follow the requirements provided in [Table 5.2.36‑1](10-tabapi-operation-definition.md#Table_5.2.36-1). - -::: {#Table_5.2.36-1 .TH} -Table 5.2.36-1: NGSI-LD ListProperty data type definition -::: - -::: TAL -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+=====================================================================================+==============================================================================================================================================================================================================================================================================================+===================================================================================================================================================+=========================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["ListProperty"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueList | An array of JSON values as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | See NGSI-LD Value definition in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms) | 1 | Ordered array of Property Values. | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property list values. | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [ListProperty]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the [ListProperty]{.HTML_Keyboard} guaranteeing its integrity. | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | 0..1 | The native JSON-LD *\@type* for the *valueList* attribute. A String Value which shall be type coerced to a URI based on the supplied *\@context*. | | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property | See datatype definition in clauses [5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the [ListProperty]{.HTML_Keyboard}. | -| | | | | | -| | or Property[] (see note 1) | | | | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperties]{.HTML_Keyboard} of the [ListProperty]{.HTML_Keyboard}. | -| | | | | | -| | or GeoProperty[] (see note 1) | | | | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperties]{.HTML_Keyboard} of the [ListProperty]{.HTML_Keyboard}. | -| | | | | | -| | or LanguageProperty[] (see note 1) | | | | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} of the [ListProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperties]{.HTML_Keyboard} of the [ListProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListProperty]{.HTML_Definition} | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperties]{.HTML_Keyboard} of the [ListProperty]{.HTML_Keyboard}. | -| | | | | | -| | or [ListProperty]{.HTML_Definition}[] (see note 1) | | | | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the [ListProperty]{.HTML_Keyboard}. | -| | | | | | -| | or Relationship[] (see note 2) | | | | -| +-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationships]{.HTML_Keyboard} of the [ListProperty]{.HTML_Keyboard}. | -+-------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.36-2) of the *ListProperty* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.36-2 .TH} -Table 5.2.36-2: Additional members of the NGSI-LD ListProperty data type -::: - -::: TAL -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+===================+=====================================================================================+====================================================================================================================+=============+==============================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of ListProperties | 0..1 | URI uniquely identifying a ListProperty instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousValueList | An array of JSON values as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | See NGSI-LD Value definition in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms) | 0..1 | Ordered array of previous Property Values. | -+-------------------+-------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.37 ListRelationship {#tablistrelationship number="10.2.37"} - -This type represents the data needed to define a *ListRelationship* as mandated by [clause 4.5.22](9-tabcontext-information-management-framework.md#tabngsi-ld-listrelationship-representations). Note that in case of concise representation, the *type* can be omitted (see [clause 4.5.22.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listrelationship)) and the *objectList* may also be represented as an ordered array of Strings. - -The supported JSON members shall follow the requirements provided in [Table 5.2.37‑1](10-tabapi-operation-definition.md#Table_5.2.37-1). - -::: {#Table_5.2.37-1 .TH} -Table 5.2.37-1: NGSI-LD ListRelationship data type definition -::: - -::: TAL -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+=======================================================+==============================================================================================================================================================================================================================================================================================+==============================================================+=============================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["ListRelationship"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| objectList | JSON Object[] or | [In the normalized form, each array element holds a JSON object containing a single Attribute with a key called ]{.ondemand_CHAR_size_9}["object"]{.HTML_Code}[and where the value is a valid URI.]{.ondemand_CHAR_size_9} | 1 | Ordered array of Relationship target objects. | -| | | | | | -| | String[] | In the concise form, each string in the array holds a valid URI | | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of relationship list objects. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [ListRelationship]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the [ListRelationship]{.HTML_Keyboard} guaranteeing its integrity. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| objectType | String or String[] | 0..1 | Node Type of the Relationship's target object. | | -| | | | | | -| | | | Both short hand string(s) (type name) or URI(s) are allowed. | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property or Property[] (see note 1) | See datatype definition in [clause 5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the [ListRelationship]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperties]{.HTML_Keyboard} of the [ListRelationship]{.HTML_Keyboard}. | -| | | | | | -| | or GeoProperty[] (see note 1) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperties]{.HTML_Keyboard} of the [ListRelationship]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} of the [ListProperty.]{.HTML_Keyboard} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperties]{.HTML_Keyboard} of the [ListRelationship]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListProperty]{.HTML_Definition} | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperties]{.HTML_Keyboard} of the [ListRelationship]{.HTML_Keyboard}. | -| | | | | | -| | or ListProperty[] (see note 1) | | | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship or Relationship[] (see note 2) | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the [ListRelationship]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationships]{.HTML_Keyboard} of the [ListRelationship.]{.HTML_Keyboard} | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.37-2) of the *ListRelationship* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context Producers]{.HTML_Keyboard}. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.37-2 .TH} -Table 5.2.37-2: Additional members of the NGSI-LD ListRelationship data type -::: - -::: TAL -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+====================+====================+===========================================================================================================================================================================================================================================+=============+================================================================================================================================================================================================================================================================+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityList | Entity[] | See datatype definition in [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) | 0..1 | An array of inline Entities obtained by [Linked Entity]{.HTML_Keyboard} retrieval, corresponding to the *ListRelationship*'s target objects See [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation). | -| | | | | | -| | | Only used in [Linked Entity]{.HTML_Keyboard} Retrieval, if the *join=inline* option is explicitly requested | | | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of *ListRelationships* | 0..1 | URI uniquely identifying a *ListRelationship* instance as mandated by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3)]{.ondemand_CHAR_name_Arial_size_9} | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousObjectList | JSON Object[] or | [In the normalized form, each array element holds a JSON object containing a containing a single Attribute with a key called ]{.ondemand_CHAR_size_9}["object"]{.HTML_Code}[and where the value is a valid URI.]{.ondemand_CHAR_size_9} | 0..1 | Ordered array of previous *Relationship* target objects. | -| | | | | | -| | String[] | In the concise form, each string in the array holds a valid URI | | | -+--------------------+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.38 JsonProperty {#tabjsonproperty number="10.2.38"} - -This type represents the data needed to define a JsonProperty as mandated by [clause 4.5.24](9-tabcontext-information-management-framework.md#tabngsi-ld-jsonproperty-representations). In case of concise representation, the *type* can be omitted (see [clause 4.5.24.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-jsonproperty)). - -The supported JSON members shall follow the requirements provided in [Table 5.2.38‑1](10-tabapi-operation-definition.md#Table_5.2.38-1). - -::: {#Table_5.2.38-1 .TH} -Table 5.2.38-1: NGSI-LD JsonProperty data type definition -::: - -::: TAL -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================================+=======================================================+==============================================================================================================================================================================================================================================================================================+==============================================================================================================================================+========================================================================================================================================================================================================================================+ -| type | String | It shall be equal to ["JsonProperty"]{.HTML_Code} | 1 | Node type. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| json | JSON | 1 | Raw unexpandable JSON which shall not be interpreted as JSON-LD using the supplied *\@context.* | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | String | Valid URI | 0..1 | It allows identifying a set or group of property values. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System temporal Property representing the expiration date for the storage of the [JsonProperty]{.HTML_Keyboard}. See [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes) | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ngsildproof | Property | Property with the non-reified subproperties "entityIdSealed" and "entityTypeSealed" as specified in [[35]](7-tabreferences.md#35). The value of its "value" element shall be an object containing the W3C^®^ Data integrity "proof" structure [[35]](7-tabreferences.md#35). | 0..1 | Cryptographic signature of the [JsonProperty]{.HTML_Keyboard} guaranteeing its integrity. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | *DateTime*[(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | Timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| valueType | String | 0..1 | The native JSON-LD *\@type* for the *json* attribute. A String Value which shall be type coerced to a URI based on the supplied *\@context*. | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Property | See datatype definitions in clauses [5.2.5](10-tabapi-operation-definition.md#tabproperty) | 0..N | Properties of the [JsonProperty.]{.HTML_Keyboard} | -| | | | | | -| | or Property[] (see note 1) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoProperty | See datatype definition in [clause 5.2.7](10-tabapi-operation-definition.md#tabgeoproperty) | 0..N | [GeoProperties]{.HTML_Keyboard} of the [JsonProperty]{.HTML_Keyboard}. | -| | | | | | -| | or GeoProperty[] (see note 1) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 1) | See datatype definition in [clause 5.2.32](10-tabapi-operation-definition.md#tablanguageproperty) | 0..N | [LanguageProperties]{.HTML_Keyboard} of the [JsonProperty]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 1) | See datatype definition in [clause 5.2.38](10-tabapi-operation-definition.md#tabjsonproperty) | 0..N | [JsonProperties]{.HTML_Keyboard} of the [JsonProperty]{.HTML_Keyboard}[.]{.HTML_Definition} | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 1) | See datatype definition in [clause 5.2.35](10-tabapi-operation-definition.md#tabvocabproperty) | 0..N | [VocabProperties]{.HTML_Keyboard} of the [JSONProperty]{.HTML_Keyboard}. | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [ListProperty]{.HTML_Definition} | See datatype definition in [clause 5.2.36](10-tabapi-operation-definition.md#tablistproperty) | 0..N | [ListProperties]{.HTML_Keyboard} of the [JsonProperty.]{.HTML_Keyboard} | -| | | | | | -| | or ListProperty[] (see note 1) | | | | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Relationship | See datatype definition in [clause 5.2.6](10-tabapi-operation-definition.md#tabrelationship) | 0..N | Relationships of the [JsonProperty]{.HTML_Keyboard}. | -| | | | | | -| | or Relationship[] (see note 2) | | | | -| +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 2) | See datatype definition in [clause 5.2.37](10-tabapi-operation-definition.md#tablistrelationship) | 0..N | [ListRelationships]{.HTML_Keyboard} of the [JsonProperty]{.HTML_Keyboard}. | -+-------------------------------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| For each *Property* (or subclass of *Property* ) identified by the same Property name, there can be one or more instances separated by *datasetId.* | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| For each *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name, there can be one or more instances separated by *datasetId.* | -| ::: | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.38-2) of the JsonProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by *Context Producers*. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.38-2 .TH} -Table 5.2.38-2: Output only members of the NGSI-LD JsonProperty data type -::: - -::: TAL -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | Data Type | Restrictions | Cardinality | Description | -+==============+=============+===================================================================================================================+=============+================================================================================================================================================================================================+ -| createdAt | String | *DateTime*[(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deletedAt | String | *DateTime*[(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated deletion timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -| | | | | | -| | | It is only used in notifications reporting deletions | | | -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| instanceId | String | Valid URI. Only used in temporal representation of [JsonProperties]{.HTML_Keyboard} | 0..1 | URI uniquely identifying a [JsonProperty]{.HTML_Keyboard} instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). | -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime*[(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| previousJson | JSON | Only used in Notifications | 0..1 | Previous *JsonProperty's* *json.* | -+--------------+-------------+-------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.39 EntityMap {#tabentitymap number="10.2.39"} - -This type represents the data needed to define an *EntityMap* as mandated by [clause 4.5.25](9-tabcontext-information-management-framework.md#tabngsi-ld-entitymap-representation). - -The supported JSON members shall follow the requirements provided in [Table 5.2.39‑1](10-tabapi-operation-definition.md#Table_5.2.39-1). - -::: {#Table_5.2.39-1 .TH} -Table 5.2.39-1: NGSI-LD EntityMap data type definition -::: - -::: TAL -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=============+========================================================================================================================+=============+====================================+ -| id | String | Valid URI | 1 | EntityMap ID. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------+ -| type | String | It shall be equal to ["EntityMap"]{.HTML_Code} | 1 | Node type. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------+ -| expiresAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Expiration date for the EntityMap. | -+-------------+-------------+------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.39-2) of the *EntityMap* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by [Context]{.HTML_Keyboard}[Consumers]{.HTML_Keyboard}. In the event that they are provided in update operations NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.39-2 .TH} -Table 5.2.39-2: Additional members of the NGSI-LD EntityMap data type -::: - -::: TAL -+-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+=============+=============+=================================================================================================================================================================================================================================================================================================================================================+=============+===============================================================================================================================+ -| entityMap | JSON | A set of key-value pairs whose keys shall be strings representing Entity ids and whose values shall be an array holding every CSourceRegistration id which is relevant to the ongoing Context Information Consumption request (see [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)). | 1 | System generated mapping of Entities to CSourceRegistrations. | -| | | | | | -| | | The key ["@none"]{.HTML_Code} shall be used to refer to an Entity that is held locally. | | | -+-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ -| linkedMaps | JSON | A set of key-value pairs whose keys shall be strings representing CSourceRegistration ids which are relevant to the ongoing Context Information request and whose values shall represent the associated EntityMap id used by the ContextSource. | 1 | System generated mapping of Context CSourceRegistrations to a URI indicating which EntityMaps was used by the Context Source. | -+-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.40 Context Source Identity {#tabcontext-source-identity number="10.2.40"} - -This type represents the data uniquely identifying a [Context Source]{.HTML_Keyboard}, and if the [Context Source]{.HTML_Keyboard} supports multi-tenancy (see [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)) uniquely identifying a [Tenant]{.HTML_Keyboard} within that [Context Source.]{.HTML_Keyboard} - -The supported JSON members shall follow the requirements provided in [Table 5.2.40‑1](10-tabapi-operation-definition.md#Table_5.2.40-1). - -::: {#Table_5.2.40-1 .TH} -Table 5.2.40-1: Context Source Identity data type definition -::: - -::: TAL -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=====================+=============+====================================================================================================================+================================================================================================================================================================================================================+==============================================================================================================================================================================================================================================================+ -| id | String | Valid URI | 1 | Context Source ID. | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["ContextSourceIdentity"]{.HTML_Code} | 1 | JSON-LD *\@type.* | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceAlias | String | Non-empty string. Pseudonym field as defined in IETF RFC 7230 [[27]](7-tabreferences.md#27) | 1 | A unique id for a [Context Source]{.HTML_Keyboard} which can be used to identify loops. | -| | | | | | -| | | | | In the multi-tenancy use case (see [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)), this id shall be identifying a specific [Tenant]{.HTML_Keyboard} within a registered [Context Source]{.HTML_Keyboard}. | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceUptime | String | String representing a duration in ISO 8601 [[17]](7-tabreferences.md#17) format | 1 | Total Duration that the [Context Source]{.HTML_Keyboard} has been available. | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceTimeAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Current time observed at the [Context Source]{.HTML_Keyboard}. Timestamp See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| contextSourceExtras | JSON | 0..1 | Instance specific information relevant to the configuration of the [Context Source]{.HTML_Keyboard} itself in raw un-expandable JSON which shall not be interpreted as JSON-LD using the supplied *\@context.* | | -+---------------------+-------------+--------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.41 Snapshot {#tabsnapshot number="10.2.41"} - -This type represents the data needed to create and manage a Snapshot. - -The supported JSON members shall follow the requirements provided in [Table 5.2.41‑1](10-tabapi-operation-definition.md#Table_5.2.41-1). - -::: {#Table_5.2.41-1 .TH} -Table 5.2.41-1: Snapshot data type definition -::: - -::: TAL -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=========================+==================+==========================================================================================================================================+============================================================================+==================================================================================================================================================================================================================================================================================================================================================================================================================+ -| id | String | Valid URI | 0..1 | System-generated at creation time, if it is not provided. It cannot be later modified in update operations. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["Snapshot"]{.HTML_Code} | 1 | JSON-LD \@type. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotQueries | Query[] | List of Query [(clause 5.2.23](10-tabapi-operation-definition.md#tabquery)), where no Query no ["temporalQ"]{.HTML_Code} element. | 0..1 | Allows clients to specify a list of queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of ["snapshotQueries"]{.HTML_Code} or ["snapshotTemporalQueries"]{.HTML_Code} shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status or cloning the Snapshot. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotTemporalQueries | Query[] | List of Query [(clause 5.2.23](10-tabapi-operation-definition.md#tabquery)), where each Query has ["temporalQ"]{.HTML_Code} element. | 0..1 | Allows clients to specify a list of temporal queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of ["snapshotQueries"]{.HTML_Code} or ["snapshotTemporalQueries"]{.HTML_Code} shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotLifetime | String | String representing a duration in ISO 8601 [[17]](7-tabreferences.md#17) format | 0..1 | Suggested duration for which the requester wants the Snapshot to exist with respect to the current point in time. The actual expiresAt time of the Snapshot shall be set by the NGSI-LD system, possibly overriding the requested duration. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotPriority | Number | Positive Integer between 1 and 10 | 0..1 | The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It can be used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endpoint | String | [Dereferenceable URI]{.HTML_Definition} | 0..1 | URI to which notifications regarding changes in the status of the Snapshot are to be sent. The information contained in the receiverInfo member shall be considered. | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| receiverInfo | KeyValuePair[] | 0..1 | Generic {key, value} array to convey optional information to the receiver. | | -+-------------------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -The following **output only** members (defined by Table 5.2.41-2) of the *Snapshot* data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by *Context Consumers*. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them. - -::: {#Table_5.2.41-2 .TH} -Table 5.2.41-2: Output only members of the Snapshot data type -::: - -::: TAL -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+================================+============================+=============================================================================================================================================================+=============+=====================================================================================================================================================================================================================================+ -| snapshotStatus | String | [It shall be one of:]{.HTML_Definition} | 1 | Allows clients to check the status of the Snapshot. | -| | | | | | -| | | ["preparing","success","partial",]{.HTML_Code} | | | -| | | | | | -| | | ["failure"]{.HTML_Code} | | | -| | | | | | -| | | or ["empty"]{.HTML_Code} | | | -| | | | | | -| | | [The initial status shall be ]{.HTML_Definition}["preparing"]{.HTML_Code}*.* | | | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotQueriesDetails | ExecutionResultDetails[] | [List of ]{.HTML_Definition}*ExecutionResultDetails* [[(clause 5](10-tabapi-operation-definition.md#tabapi-operation-definition).2.42)]{.HTML_Definition} | 0..1 | List with one result per Snapshot query execution, in the same order as Snapshot queries. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotTemporalQueriesDetails | ExecutionResultDetails[] | [List of ]{.HTML_Definition}*ExecutionResultDetails* [[(clause 5](10-tabapi-operation-definition.md#tabapi-operation-definition).2.42)]{.HTML_Definition} | 0..1 | List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| createdAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated creation timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| modifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated last modification timestamp. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Expiration time for the snapshot - it is possible to indirectly update the member by updating snapshotLifetime. | -| | | | | | -| | | | | See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastUsedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 0..1 | System generated timestamp identifying the point in time when the snapshot was most recently used. It is initialized at creation time. See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.42 ExecutionResultDetails {#tabexecutionresultdetails number="10.2.42"} - -This type represents the details of the result of execution a request, e.g. a Query. - -The supported JSON members shall follow the requirements provided in [Table 5.2.42‑1](10-tabapi-operation-definition.md#Table_5.2.42-1). - -::: {#Table_5.2.42-1 .TH} -Table 5.2.42-1: ExecutionResultDetails data type definition -::: - -::: TAL -+----------------+-------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+================+=============+======================================================================+=============+========================================================================================================================================================================================+ -| problemDetails | \@JSON | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 0..1 | Provides more details regarding the result status, especially when reporting an error. | -+----------------+-------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| resultStatus | String | *It shall be one of:* | 1 | Describes the status of the result. ["failure"]{.HTML_Code}, if an error is reported, ["success" ]{.HTML_Code}in case of a non-empty result and ["empty"]{.HTML_Code} otherwise. | -| | | | | | -| | | ["success",]{.HTML_Code} | | | -| | | | | | -| | | ["failure"]{.HTML_Code} | | | -| | | | | | -| | | or ["empty"]{.HTML_Code} | | | -+----------------+-------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.43 OrderingParams {#taborderingparams number="10.2.43"} - -This datatype represents the parameters that convey the definition used whilst ordering Entities. - -The supported JSON members shall follow the requirements provided in [Table 5.2.43‑1](10-tabapi-operation-definition.md#Table_5.2.43-1). - -::: {#Table_5.2.43-1 .TH} -Table 5.2.43-1: OrderingParams data type definition -::: - -::: TAL -+-------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+=============+=============+============================================================================================================================================================================================================================================================================================================================================================================+=====================================================+=============================================================================================================================================================================+ -| collation | String | An ICU collation (see IETF RFC 6067 [[36]](7-tabreferences.md#36)). | 0..1 | The Entities returned in the payload shall be ordered according to the collation given. By default, it shall be ICU "root" collation order (["und-x-icu"]{.HTML_Code}). | -+-------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| coordinates | JSON Array | A JSON Array coherent with the geometry type as per IETF RFC 7946 [[8]](7-tabreferences.md#8). | 0..1 | Coordinates of a Geometry used when sorting by distance. | -| | | | | | -| | | | It shall be one if *orderBy* uses order by distance | | -+-------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | A valid GeoJSON [[8]](7-tabreferences.md#8) geometry type excepting *GeometryCollection*[.]{.HTML_Definition} | 0..1 | The type of geometry whose coordinates are used when sorting by distance. By default, it shall be a ["Point"]{.HTML_Code} geometry. | -+-------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| orderBy | String[] | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) appended with an optional sorting style (["asc"]{.HTML_Code}, ["desc"]{.HTML_Code}, ["dist-asc"]{.HTML_Code}, ["dist-desc") ]{.HTML_Code}as per [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering). | 1 | When defined, the Entities returned in the payload shall be ordered according to members defined. | -+-------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.2.44 AggregationParams {#tabaggregationparams number="10.2.44"} - -This datatype represents the parameters required for supporting aggregation methods in temporal requests. - -The supported JSON members shall follow the requirements provided in [Table 5.2.44‑1](10-tabapi-operation-definition.md#Table_5.2.44-1). - -::: {#Table_5.2.44-1 .TH} -Table 5.2.44-1: AggregationParams data type definition -::: - -::: TAL -+--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ -| Name | Data Type | Restriction | Cardinality | Description | -+====================+=================================+==========================================================================================================================================================================================================+=============+=============+ -| aggrMethods | Comma separated list of strings | Each String represents an aggregation method, as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). | 1 | \- | -+--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ -| aggrPeriodDuration | String | It represents the duration of each period used for the aggregation as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). | 0..1 | \- | -| | | | | | -| | | If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. | | | -+--------------------+---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+ -::: - -## 5.3 Notification data types {#tabnotification-data-types number="10.3"} - -### 5.3.1 Notification {#tabnotification number="10.3.1"} - -This datatype represents the parameters that allow building a notification to be sent to a subscriber. How to build this notification is detailed in [clause 5.8.6](10-tabapi-operation-definition.md#tabnotification-behaviour). - -The supported JSON members shall follow the indications provided in [Table 5.3.1‑1](10-tabapi-operation-definition.md#Table_5.3.1-1). - -::: {#Table_5.3.1-1 .TH} -Table 5.3.1-1: Notification data type definition -::: - -::: TAL -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+================+=========================================+====================================================================================================================+========================================================================================================================================================================================================================================================================================================================================================+======================================================================================================+ -| id | String | Valid URI | 1 | Notification identifier (JSON-LD *\@id*). It shall be automatically generated by the implementation. | -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["Notification"]{.HTML_Code} | 1 | JSON-LD *\@type.* | -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| data | NGSI-LD Entity[] or FeatureCollection | 1 | The content of the notification as NGSI-LD Entities. See [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). | | -| | | | | | -| | | | If the notification has been triggered from a Subscription that has the *notification.* | | -| | | | | | -| | | | *endpoint.accept* field set to [application/geo+json]{.HTML_Code}then [data]{.PL} is returned as a *FeatureCollection*. In this case, if the *notification.endpoint.receiverInfo*contains the key ["Prefer"]{.HTML_Code} and it is set to the value ["body=json"]{.HTML_Code}, then the *FeatureCollection* will not contain an *\@context* field. | | -| | | | | | -| | | | If *endpoint.accept* is not set or holds another value then Entity[] is returned. | | -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| notifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| subscriptionId | String | Valid URI | 1 | Identifier of the subscription that originated the notification. | -+----------------+-----------------------------------------+--------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -::: - -### 5.3.2 CSourceNotification {#tabcsourcenotification number="10.3.2"} - -This datatype represents the parameters that allow building a [Context Source]{.HTML_Keyboard} Notification to be sent to a subscriber. How to build this notification is detailed in [clause 5.11.7](10-tabapi-operation-definition.md#tabnotification-behaviour-1). - -The supported JSON members shall follow the indications provided in [Table 5.3.2‑1](10-tabapi-operation-definition.md#Table_5.3.2-1). - -::: {#Table_5.3.2-1 .TH} -Table 5.3.2-1: CSourceNotification data type definition -::: - -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| id | String | Valid URI | 1 | CSource notification identifier (JSON-LD *\@id*). | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| type | String | It shall be equal to ["ContextSourceNotification"]{.HTML_Code} | 1 | JSON-LD *\@type*. | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | | -| | | | | | -| data | CSource | 1 | The content of the notification as NGSI-LD CSourceRegistrations. See [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration). | | -| | | | | | -| | Registration[] | | | | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| notifiedAt | String | *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| subscriptionId | String | Valid URI | 1 | Identifier of the subscription that originated the notification. | -+----------------+------------------+------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| triggerReason | String | *TriggerReasonEnumeration* (see [clause 5.3.3](10-tabapi-operation-definition.md#tabtriggerreasonenumeration)) | 1 | Indicates whether the CSources in the CSourceRegistration(s) in data are newly matching (initial notification or creation), have been updated (but still match) or do not match any longer. | -+================+==================+========================================================================================================================+==================================================================================================================================================+=============================================================================================================================================================================================+ - -### 5.3.3 TriggerReasonEnumeration {#tabtriggerreasonenumeration number="10.3.3"} - -The enumeration can take one of the following values: - -::: B1plus -- **"newlyMatching"** - describes the case that the notified [Context Source Registration]{.HTML_Keyboard}(s) newly match(es) the identified subscription. This value is used in the first notification and whenever a new [Context Source Registration]{.HTML_Keyboard} matching the Subscription has been registered, or an existing [Context Source Registration]{.HTML_Keyboard} that did not match before has been updated in such a way that it matches now. -- **"updated"** - describes the case that the notified [Context Source Registration]{.HTML_Keyboard} that was part of a previous notification has been updated, but still matches the Subscription. -- **"noLongerMatching"** - describes the case that the notified [Context Source Registration]{.HTML_Keyboard} that was part of a previous notification no longer matches the Subscription, i.e. as a result of an update or because it was deleted. -::: - -### 5.3.4 SnapshotNotification {#tabsnapshotnotification number="10.3.4"} - -This datatype represents the parameters that allow building a snapshot notification to be sent to a subscriber. How to build this notification is detailed in [clause 5.16.6](10-tabapi-operation-definition.md#tabsnapshot-status-notification-behaviour). - -The supported JSON members shall follow the indications provided in [Table 5.3.4‑1](10-tabapi-operation-definition.md#Table_5.3.4-1). - -::: {#Table_5.3.4-1 .TH} -Table 5.3.4-1: SnapshotNotification data type definition -::: - -::: TAL -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Restrictions | Cardinality | Description | -+================================+============================+=============================================================================================================================================================+=============+=============================================================================================================================================================================================================================+ -| Id | String | Valid URI | 1 | Notification identifier (JSON-LD *\@id*). It shall be automatically generated by the implementation. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | It shall be equal to ["SnapshotNotification"]{.HTML_Code} | 1 | JSON-LD *\@type.* | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expiresAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Expiration time for the snapshot - if expiresAt is before notifiedAt, the notification indicates that the snapshot has been deleted. In this case, snapshotReady shall be set to *false*. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| notifiedAt | String | *DateTime* [(clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) | 1 | Timestamp corresponding to the instant when the notification was generated by the system. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotId | String | Valid URI | 1 | Identifier of the snapshot whose status change triggered the notification. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotPriority | Number | Positive Integer between 1 and 10 | 1 | The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It is used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotQueriesDetails | ExecutionResultDetails[] | [List of ]{.HTML_Definition}*ExecutionResultDetails* [[(clause 5](10-tabapi-operation-definition.md#tabapi-operation-definition).2.42)]{.HTML_Definition} | 0..1 | List with one result per Snapshot query execution, in the same order as Snapshot queries. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshotStatus | String | [It shall be one of:]{.HTML_Definition} | 1 | Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying. | -| | | | | | -| | | ["success","partial",]{.HTML_Code} | | | -| | | | | | -| | | ["failure"]{.HTML_Code} | | | -| | | | | | -| | | or ["empty"]{.HTML_Code} | | | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| temporalSnapshotQueriesDetails | ExecutionResultDetails[] | [List of ]{.HTML_Definition}*ExecutionResultDetails* [[(clause 5](10-tabapi-operation-definition.md#tabapi-operation-definition).2.42)]{.HTML_Definition} | 0..1 | List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries. | -+--------------------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 5.4 NGSI-LD Fragments {#tabngsi-ld-fragments number="10.4"} - -When updating NGSI-LD elements (Entities, Attributes, [Context Source Registrations]{.HTML_Keyboard} or Subscriptions) it is necessary to have a means of describing a set of modifications to their content. - -An NGSI-LD Fragment is a JSON Merge Patch document [[16]](7-tabreferences.md#16) and [[i.10]](7-tabreferences.md#i.10) which describes changes to be made to a target JSON-LD document using a syntax that closely mimics the document being modified. - -An NGSI-LD Fragment is a JSON-LD Object which shall include the following members: - -::: B1plus -- *id* (optional for certain bindings where it can be determined from the operation signature). It shall be equal to the id of the target (mutated) NGSI-LD element. Attribute Fragments do not contain explicit ids. -- *type* (optional for certain bindings where it can be determined from the operation signature). It shall contain the Type name(s) of the target NGSI-LD element. -- A member (following the same data representation and nesting structure) for each new member to be added to the target NGSI-LD element. -- A member (following the same data representation and nesting structure) for each new member to be modified in the target NGSI-LD element, which value shall correspond to the new member value to be given. -::: - -::: EX -EXAMPLE 1: - -The following Subscription Fragment allows the modification of a Subscription by changing its endpoint's URI: - -``` json -{ - "id": "urn:ngsi-ld:Subscription:MySubscription", -"type": "Subscription", -"endpoint": { - "uri": "http://example.org/newNotificationEndPoint" -} -} -``` -::: - -::: B1plus -- A member (following the same data representation and nesting structure) with value equal to an NGSI-LD Null shall cause for the member to be removed from the target NGSI-LD element. -::: - -::: EX -EXAMPLE 2: - -The following NGSI-LD Fragment allows the modification of an Entity by changing its *batteryLevel* Attribute, updating the *observedAt* sub-Attribute, removing the *providedBy* sub-Attribute and removing the *uncharged* Attribute from the Entity: - -``` json -{ -"id": "urn:ngsi-ld:TemperatureSensor:001", -"type": "TemperatureSensor", -"batteryLevel": { -"type": "Property", -"value": 7, -"observedAt": "2022-03-14T12:51:02.000Z", -"providedBy": "urn:ngsi-ld:null" -}, -"uncharged" : { -"type": "Property", -"value": "urn:ngsi-ld:null" -} -} -``` -::: - -## 5.5 Common Behaviours {#tabcommon-behaviours number="10.5"} - -### 5.5.1 Introduction {#tabintroduction-17 number="10.5.1"} - -This clause defines common behaviours for the API operations. - -When comparing URIs, implementations shall follow the recommendations of IETF RFC 3986 [[5]](7-tabreferences.md#5), section 6. - -### 5.5.2 Error types {#taberror-types number="10.5.2"} - -[Table 5.5.2‑1](10-tabapi-operation-definition.md#Table_5.5.2-1) details a list of error types defined by NGSI-LD. The particular conditions under which error type shall be raised are defined when describing each operation supported by the API. - -::: {#Table_5.5.2-1 .TH} -Table 5.5.2-1: Error types in NGSI-LD -::: - -::: TAL -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| Error Type | Description | -+===========================================================+=====================================================================================================================================================+ -| https://uri.etsi.org/ngsi-ld/errors/AlreadyExists | The referred element already exists. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/BadRequestData | The request includes input data which does not meet the requirements of the operation. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/Conflict | The operation conflicts with the current state of the system. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/InternalError | There has been an error during the operation execution. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/InvalidRequest | The request associated to the operation is syntactically invalid or includes wrong content. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable | A remote JSON-LD \@context referenced in a request cannot be retrieved by the NGSI-LD Broker and expansion or compaction cannot be performed. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport | The NGSI-LD API implementation does not support multiple tenants. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant | The addressed tenant does not exist. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported | The operation is not supported. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound | The referred resource has not been found. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery | The query associated to the operation is too complex and cannot be resolved. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/TooManyResults | The query associated to the operation is producing so many results that can exhaust client or server resources. It should be made more restrictive. | -+-----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 5.5.3 Error response payload body {#taberror-response-payload-body number="10.5.3"} - -When reporting errors back to clients, NGSI-LD implementations shall generate a JSON object in accordance with IETF RFC 7807 [[10]](7-tabreferences.md#10), section 3.1, including, at least the following terms: - -::: B1plus -- **type:** Error type as per [clause 5.5.2](10-tabapi-operation-definition.md#taberror-types). -- **title:** Error title which shall be a short string summarizing the error. -- **detail:** A detailed message that should convey enough information about the error. -::: - -Even though IETF RFC 7807 [[10]](7-tabreferences.md#10) defines a specific MIME type for error payloads, NGSI-LD implementations shall use the standard JSON MIME type (["application/json"]{.HTML_Code}) when reporting errors, so that old clients or existing tools are not broken. - -::: EX -EXAMPLE: - -``` json -{ -"type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound", -"title": "Resource not found.", -"detail": "urn:ngsi-ld:Device:widget001 was not found", -"status": 404, -"instance": "urn:ngsi-ld:Device:widget001" -} -``` -::: - -### 5.5.4 General NGSI-LD validation {#tabgeneral-ngsi-ld-validation number="10.5.4"} - -All the operations that take a JSON-LD document as input shall process such JSON-LD document as follows: - -::: B1plus -- If the request payload body is not a valid JSON document then an error of type *InvalidRequest* shall be raised. -- If the data included by the JSON-LD document is not syntactically correct, according to the [\@context]{.HTML_Variable} or the API data type definitions, then an error of type [BadRequestData]{.HTML_Error} shall be raised. -- A [Context Producer]{.HTML_Keyboard} may supply an additional hint regarding the overall validity of the payload body and the version of the NGSI-LD specification that the API datatype definitions conform to. When receiving such an annotated context production request, a [Context Broker ]{.HTML_Keyboard}that it is only partially capable of interpreting the datatypes held within the payload body may use this information to amend the data held within the payload through applying fallbacks (see [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads)) prior to validation. -- Any attempt to use ["urn:ngsi-ld:null"]{.HTML_Code} as a first level member value [("": "urn:ngsi-ld:null"]{.HTML_Code}*)*, with the exception of NGSI-LD Fragments (see [clause 5.4](10-tabapi-operation-definition.md#tabngsi-ld-fragments)) used in partial update and merge operations (as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [clause 5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) or to represent deleted Properties in concise representation as part of notifications, shall result in an error of type *BadRequestData*. -- Any attempt to use ["urn:ngsi-ld:null]{.HTML_Code}*"* as the right-hand side of *value* in a *Property*, as the right-hand side of *object* in a *Relationship* or to use [{"@none": "urn:ngsi-ld:null"} ]{.HTML_Code}as the right-hand side of *languageMap*, with the exception of NGSI-LD Fragments (see [clause 5.4](10-tabapi-operation-definition.md#tabngsi-ld-fragments)) used in update and merge operations (as mandated by clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) and the representation of deleted Properties, Relationships or Language Properties in notifications and the temporal evolution, shall result in an error of type *BadRequestData*. -- Any attempt to use ["urn:ngsi-ld:null]{.HTML_Code}*"* as the value of a key value pair within a JSON object, which is the right-hand side of the *value* of a Property, with the exception of NGSI-LD Fragments used in merge operations (see [clause 5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)), shall result in an error of type *BadRequestData*. -::: - -### 5.5.5 Default \@context assignment {#tabdefault-context-assignment number="10.5.5"} - -If the input provided by an API client does not include any *\@context,* then the implementation shall at minimum assign the Core \@context to such an input. In addition, the [Context Broker]{.HTML_Keyboard} implementation may allow configuring a default user *\@context* (with default terms), to be used when no user *\@context* is provided. The Core *\@context* shall always take precedence. - -### 5.5.6 Operation execution and generic error handling {#taboperation-execution-and-generic-error-handling number="10.5.6"} - -When executing an operation if an unexpected error happens and the operation cannot be completed, implementations shall raise an error of type *InternalError*. This includes, as well, situations such as database timeouts, etc. - -If the NGSI-LD endpoint is not capable of executing the requested operation, an error of type *OperationNotSupported* shall be raised. This may happen in a distributed architecture where a [Context Broker]{.HTML_Keyboard} might not be able to store Entities (only to forward queries to [Context Sources]{.HTML_Keyboard}), and as a result, certain operations such as "Create Entity" might not be supported. - -When a query operation is so complex that cannot be resolved by an NGSI-LD system, implementations shall raise an error of type *TooComplexQuery*. - -When a query operation is producing so many results that can potentially exhaust client or server resources, or it can be just impractical to be managed, implementations shall raise an error of type *TooManyResults*. The threshold conditions used as criteria to raise such error is up to each implementation. - -When a remote JSON-LD *\@context* referenced by an incoming request is not available, implementations shall raise an error of type *LdContextNotAvailable*. If the remote JSON-LD *\@context* is invalid, implementations shall raise an error of type *BadRequestData*. - -### 5.5.7 Term to URI expansion or compaction {#tabterm-to-uri-expansion-or-compaction number="10.5.7"} - -NGSI-LD API operations allow clients to use short-hand strings as non-qualified names, particularly for *Property*, *Relationship* or Type names and [VocabProperty]{.HTML_Keyboard} values. For instance, an API client can refer to the term ["Vehicle"]{.HTML_Code} as a non-qualified type name. When executing API update-related operations, NGSI-LD systems shall expand terms to URIs, in order to obtain and store Fully Qualified Names. Likewise, when executing query-related operations, NGSI-LD systems shall compact URIs (Fully Qualified Names) to short terms in order to provide short-hand strings to context consumers. - -The term to URI expansion or compaction shall be performed using a *\@context* as described by the JSON-LD specification [[2]](7-tabreferences.md#2), section 5.1, and in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). **In the absence of a user** *\@context***, the term expansion or compaction shall be performed according to [clause 5.5.5](10-tabapi-operation-definition.md#tabdefault-context-assignment)**. - -For the avoidance of doubt, the *\@context* used to perform compaction or expansion of terms **shall be the one provided by each API call** (or the default *\@context* in its absence), and not any other *\@context* which might have been supplied previously. For instance, when performing "Query Entity" operations [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)), the *\@context* used to perform URI expansion and compaction shall be the one provided by the request. - -In case of HTTP binding via GET (clause 6.4.3.2) of the "Query Entity" operation, this means using the JSON-LD Link Header as described by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2. In case of HTTP binding via POST [(clause 6.23.3.1](11-tabapi-http-binding.md#tabpost-11)), of the "Query Entity" operation, this means giving the *\@context* either via Link Header or within the payload body, depending on the Content-Type Header being ["]{.HTML_Code}[application/json]{.HTML_Code}["]{.HTML_Code} or ["]{.HTML_Code}[application/ld+json]{.HTML_Code}["]{.HTML_Code}, respectively. - -It is important to warn users that updating a *\@context* could lead to behaviour that might be perceived as inconsistent. If, for instance, a fully qualified name that qualified a given short-hand name is changed, from that moment onwards, the short-hand name is referencing a different Attribute. This will effectively change the results of queries that use the given short name, possibly not giving back anymore the expected set of results. - -Moreover, this user *\@context* shall not: - -::: B1plus -- Contain JSON-LD Scoped Contexts (see [[2]](7-tabreferences.md#2), section 4.1.8). -- Be embedded into NGSI-LD Attributes, i.e. there cannot be parts of the user *\@context* other than at the top level of the NGSI-LD document. -::: - -Parts of user *\@context* that are not following the two points above should result in an error of type *BadRequestData*, because JSON-LD Scoped Contexts and nested embedded *\@context* could be used to modify terms defined in the Core \@context or to reshape NGSI-LD Elements during the expansion of terms. - -As the Core \@context is protected and cannot be overridden, when performing term to URI expansion or compaction, implementations **shall always consider the Core** *\@context* **as having absolute precedence**, regardless of the position of the Core *\@context* in the *\@context* array of elements. Nonetheless, NGSI-LD data providers may use appropriate term prefixing to ensure that a proper term to URI expansion or compaction is performed. - -At compaction time, in the event that no matching term is found in the current *\@context*, implementations shall render Fully Qualified Names. - -::: EX -EXAMPLE: - -An entity of type ["Vehicle"]{.HTML_Code} bound to a certain *\@context* , C, will match a query by ["Vehicle" ]{.HTML_Code} type if and only if the supplied query *\@context* , Q, maps the term ["Vehicle"]{.HTML_Code} to the same URI as C. -::: - -::: ondemand_PAR_space_after_10 -Note that the *JsonProperty* is designed to hold native JSON values which are by definition not available for expansion and compaction via an *\@context*. Therefore, the given short-hand name is always used for accessing JSON keys within a *JsonProperty* *json* element. -::: - -### 5.5.8 Partial Update Patch Behaviour {#tabpartial-update-patch-behaviour number="10.5.8"} - -The Partial Update Patch procedure modifies an existing NGSI-LD element by overwriting the data at the Attribute level, replacing it with the data provided in the NGSI-LD Fragment. - -When updating NGSI-LD elements (Entities, [Context Source Registrations]{.HTML_Keyboard} or Context Subscriptions) using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element. - -With respect to update operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [[16]](7-tabreferences.md#16)), in order to observe the name to URI expansion rules and the JSON-LD *null* processing): - -::: B1plus -- For each member of the Fragment perform the term to URI expansion. -- If the provided Fragment (a JSON Merge Patch document) contains members that do not appear within the target (their URIs do not match), those members are added to the target. -- For each member of the Fragment contained by the target, the target member value is replaced by the value given in the Fragment. In the case of a member representing a reified Property or Relationship including a *datasetId*, such member is only replaced if the *datasetId* is the same, otherwise the member of the Fragment is added as a new instance to the target. If no *datasetId* is present, the default Attribute instance is targeted and replaced if present and otherwise added. In case of a member *type* (of an entity) in Entity Fragments, all included Entity Types are added, if they are not already contained in the *type* member of the target. -- For each member of the Fragment, whose value is an NGSI-LD Null*,* contained by the target, the target member is deleted. In the case of deleting a specific Attribute instance with a *datasetId*, the handling shall be in accordance with the description found in [clause 5.6.5](10-tabapi-operation-definition.md#tabdelete-attribute). A *datasetId* cannot be deleted by setting it to the value ["urn:ngsi-ld:null".]{.HTML_Code} -::: - -::: EX -EXAMPLE 1: - -Given an Entity containing the following Property: - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 25, -"unitCode": -"CEL" -"observedAt": -"2022-03-14T01:59:26.535Z" -} -} -``` - -``` json -{ -"type": -"Property", -"value": 100, -"observedAt": -"2022-03-14T13:00:00.000Z" -} -``` - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 100, -"unitCode": -"CEL" -"observedAt": -"2022-03-14T13:00:00.000Z" -} -} -``` -::: - -::: EX -EXAMPLE 2: - -Given an Entity containing the following *Property* : - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 25, -"unitCode": -"CEL" -"observedAt": -"2022-03-14T01:59:26.535Z" -} -} -``` - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 100, -"observedAt": -"2022-03-14T13:00:00.000Z" -} -} -``` - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 100, -"observedAt": -"2022-03-14T13:00:00.000Z" -} -} -``` -::: - -::: EX -EXAMPLE 3: - -Given an Entity containing the following *Property* : - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": 25, -"unitCode": -"CEL" -"observedAt": -"2022-03-14T01:59:26.535Z" -} -} -``` - -``` json -{ -"temperature": -{ -"type": -"Property", -"value": -} -} -``` -::: - -### 5.5.9 Pagination Behaviour {#tabpagination-behaviour number="10.5.9"} - -#### 5.5.9.1 General Pagination Behaviour {#tabgeneral-pagination-behaviour number="10.5.9.1"} - -When resolving NGSI-LD Query operations, NGSI-LD Systems shall exhibit the behaviour described by the present clause: - -::: B1plus -- Let **Md** be equal to the default maximum number of NGSI-LD Elements to be retrieved by the API during each query pagination iteration, as defined by the NGSI-LD implementation. -- Let **Mc** be equal to the maximum number of NGSI-LD Elements to be retrieved as requested by the NGSI-LD Client. If **Mc** is undefined then it shall be equal to **Md**. -- Let **L** be the maximum number of NGSI-LD Elements to be retrieved by the API during each query pagination iteration. **L** shall be equal to **Mc**. -- During query execution and for each pagination iteration, the query resolution mechanisms of the NGSI-LD System shall ensure that only up to a maximum of **L** NGSI-LD Elements are retrieved and returned to the NGSI-LD client, i.e. the maximum page size per iteration shall not overpass **L**. Nonetheless, implementations shall take care of not overpassing a maximum size of response payload body, which, in practice, implies that, under certain circumstances, the number of Elements retrieved per page can be lower than **L**. -- After the retrieval of each page (containing at most **L NGSI-LD Elements**) implementations shall check whether there are pending NGSI-LD Elements to be retrieved in the context of the current query. If that is the case, implementations shall flag NGSI-LD Clients of the existence of such NGSI-LD Elements. Ultimately, the flagging mechanisms used shall depend on each API binding but shall be present as mandated by the present clause. -- When flagging the existence of additional NGSI-LD Elements (pages) pending to be retrieved, generally, implementations shall provide NGSI-LD Clients pointers to get access to both the following page of NGSI-LD Elements and the previous one, according to the current pagination iteration. -- The pointer to the previous page of NGSI-LD Elements shall be included for all pagination iterations excepting the first one, as, obviously, there will be no previous NGSI-LD Elements. -- When the last page of NGSI-LD Elements is reached, only the pointer to the previous page shall be provided to NGSI-LD Clients, so that they can detect that no more NGSI-LD Elements are available. -- The pointers to NGSI-LD Elements shall contain all the parameters needed to allow NGSI-LD Clients to retrieve the next and previous page, without further interactions with the API. -::: - -While iterating over a set of pages, there might be changes in the target result set, due to additions or removals of NGSI-LD Elements occurring in between. Implementations may detect those situations and may warn NGSI-LD Clients appropriately. During pagination, the same \@context shall be used. An attempt to use a different \@context should result in an *BadRequestData* error. - -#### 5.5.9.2 Pagination option using limit and offset {#tabpagination-option-using-limit-and-offset number="10.5.9.2"} - -The general pagination behaviour described in [clause 5.5.9.1](10-tabapi-operation-definition.md#tabgeneral-pagination-behaviour) only requires pointers to the following and previous pages, which can be implemented in a completely opaque way. Pagination may also be implemented in a transparent way, giving the Context Consumer more control over the process. In this case, the parameters *limit* and *offset* should be used, allowing the Context Consumer to adapt the size of the page using *limit* and jump to a desired set of elements in the results using *offset*. - -#### 5.5.9.3 Pagination with Entity maps {#tabpagination-with-entity-maps number="10.5.9.3"} - -In the case of queries based on Entity maps, the set of Entities considered for the result is fixed with the initial query creating the Entity map. However, the Entity information itself can be dynamic, so filters shall be rechecked before returning results. In the case of split Entities, the Entities in the Entity map can only be considered as candidate Entities, since, at the time of Entity map creation, the Entities have not been aggregated and thus the filters could not be applied. This can only be done when preparing a page for pagination. Thus, Entities not or no longer fitting the query shall be removed from the Entity map during pagination. Pages shall always be filled to the maximum, as long as Entities are available. When using the previous link, the set of Entities on the previous page may not be the same as before, due to dynamic changes resulting in Entities no longer fulfilling the filter criteria of the query. As a result, the first page when going backward, and the last page, when going forward, may have less than the maximum number of Entities. - -### 5.5.10 Multi-Tenant Behaviour {#tabmulti-tenant-behaviour number="10.5.10"} - -If a [Tenant]{.HTML_Keyboard} is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specified [Tenant]{.HTML_Keyboard}. If no [Tenant]{.HTML_Keyboard} is specified, the operation shall apply to the implicitly existing default [Tenant]{.HTML_Keyboard}. If a [Tenant]{.HTML_Keyboard} is explicitly specified, but the system implementing the NGSI-LD API does not support multi-tenancy, an error of type *NoMultiTenantSupport* should be raised. - -In case an operation applies to a [Tenant]{.HTML_Keyboard}, this information shall also be provided in the response to the operation. This also applies to notifications sent as a result of subscriptions (clauses [5.8](10-tabapi-operation-definition.md#tabcontext-information-subscription) and [5.11](10-tabapi-operation-definition.md#tabcontext-source-registration-subscription)). - -A [Tenant]{.HTML_Keyboard} is represented in form of a String. How the [Tenant]{.HTML_Keyboard} is specified for an API operation is protocol binding specific. How [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard} are created, is implementation-specific. - -One implementation option is to support the implicit creation of [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}. This means that a [Tenant]{.HTML_Keyboard} is implicitly created when an NGSI-LD operation for creating information targets a new [Tenant]{.HTML_Keyboard}; this is the case for: - -::: B1plus -- Create Entity [(clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity)). -- Batch Entity Creation [(clause 5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation)). -- Create or Update Temporal Evolution of an Entity [(clause 5.6.11](10-tabapi-operation-definition.md#tabcreate-or-update-upsert-temporal-evolution-of-an-entity)). -- Create Subscription [(clause 5.8.1](10-tabapi-operation-definition.md#tabcreate-subscription)). -- Register Context Source [(clause 5.9.2](10-tabapi-operation-definition.md#tabregister-context-source)). -- Create Context Source Registration [(clause 5.11.2](10-tabapi-operation-definition.md#tabcreate-context-source-registration-subscription)). -::: - -All other NGSI-LD operations, e.g. for retrieving, updating, appending or deleting information that target a non-existing [Tenant]{.HTML_Keyboard} should raise an error of type *NonexistentTenant*. - -If the system implementing the NGSI-LD API does not support multiple [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}, the attempt to register a [Context Source]{.HTML_Keyboard} with [Tenant]{.HTML_Keyboard} information in the [Context Source Registration]{.HTML_Keyboard} should also result in an error of type *NoMultiTenantSupport*. - -### 5.5.11 More than one instance of the same Entity in an Entity array {#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array number="10.5.11"} - -#### 5.5.11.0 Foreword {#tabforeword-3 number="10.5.11.1"} - -The following operations operate on an array of entities (as input payload): - -::: B1plus -- Batch Entity Creation [(clause 5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation)). -- Batch Entity Creation or Update (Upsert) [(clause 5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert)). -- Batch Entity Update [(clause 5.6.9](10-tabapi-operation-definition.md#tabbatch-entity-update)). -- Batch Entity Delete [(clause 5.6.10](10-tabapi-operation-definition.md#tabbatch-entity-delete)). -- Batch Entity Merge [(clause 5.6.20](10-tabapi-operation-definition.md#tabbatch-entity-merge)). -::: - -It is allowed for such an input Entity array to contain more than one instance of the same entity (those instances have identical ids). - -In order for such a request to be correctly handled, those instances that have the same *id* are processed by the Broker in the order they have in the array: the higher the index in the array, the later it will be processed. If the order is altered, the outcome may be altered. - -All Entities and Attributes in the batch will get the same *modifiedAt* timestamp, so it makes sense to distinguish them via the *observedAt* temporal property. - -Implementations shall treat the entity instances as if they had all arrived in separate requests. - -The following clauses specify the behaviour in each case. - -#### 5.5.11.1 Batch Entity Creation case {#tabbatch-entity-creation-case number="10.5.11.2"} - -The first occurrence of an entity in the input array (the oldest one) is used for the creation of the entity. Any subsequent instance of the same entity is reported as an error (entity already exists) in the response. - -#### 5.5.11.2 Batch Entity Creation or Update (Upsert) case {#tabbatch-entity-creation-or-update-upsert-case number="10.5.11.3"} - -This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing entities, while the optional behaviour is to update already existing entities. Non existing entities are created in both modes. - -If the entity does not yet exist, the first occurrence of an entity is used to create the entity, and subsequent instances of that same entity are used to either replace (default behaviour) or to update (optional behaviour) the entity. These replace or update operations shall be done **in chronological order.** - -Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in [clause 4.3.1](9-tabcontext-information-management-framework.md#tabintroduction-2)). For [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of Entities]{.HTML_Keyboard} (as defined in [clause 4.3.1](9-tabcontext-information-management-framework.md#tabintroduction-2)), all entity instances shall be taken into account, in the correct order. - -#### 5.5.11.3 Batch Entity Update case {#tabbatch-entity-update-case number="10.5.11.4"} - -This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing attributes of the entities, while the optional behaviour is to preserve already existing attributes of the entities. - -Brokers shall send separate notifications for each individual update, taking throttling into account. - -#### 5.5.11.4 Batch Entity Delete case {#tabbatch-entity-delete-case number="10.5.11.5"} - -The Batch Entity Delete operation has as input an array of Entity IDs, for the entities to be deleted. If an Entity ID is replicated in the array, the first occurrence will delete the entity, while subsequent occurrences of the same Entity ID will provoke an error in the response (entity does not exist). - -#### 5.5.11.5 Batch Entity Merge case {#tabbatch-entity-merge-case number="10.5.11.6"} - -The Batch Entity Merge operation has as input an array of Entity IDs, for the entities to be merged. If an Entity ID is replicated in the array, these merge operations shall be done **in chronological order**. Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in [clause 4.3.1](9-tabcontext-information-management-framework.md#tabintroduction-2)). For [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of Entities]{.HTML_Keyboard} (as defined in [clause 4.3.1](9-tabcontext-information-management-framework.md#tabintroduction-2)), all entity instances shall be taken into account, in the correct order. - -### 5.5.12 Merge Patch Behaviour {#tabmerge-patch-behaviour number="10.5.12"} - -The merge patch procedure modifies an existing NGSI-LD element by applying the set of changes found in an NGSI-LD Fragment data to the target resource. Unlike the partial update patch behaviour (described in [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour)), which replaces the complete element on the first level, e.g. a whole Attribute, the procedure described in this clause merges the provided information with the existing information up to an arbitrary depth, e.g. including going into JSON objects representing a Property value. - -When merging NGSI-LD Entities using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element. - -With respect to merge operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [[16]](7-tabreferences.md#16), in order to observe the name to URI expansion rules and JSON-LD *null* processing): - -::: B1plus -- For each member of the Fragment perform the term to URI expansion. -- If the provided Fragment (a JSON Merge Patch document) contains members that do not appear within the target (their URIs do not match), those members are added to the target. -- For each member of the Fragment contained by the target, the target member value is **merged** with the value given in the Fragment. NGSI-LD Nulls within the Fragment are given special meaning to indicate the removal of existing values within the target member value. In the case of a member representing a reified Property or Relationship including a *datasetId*, such member is only updated if the *datasetId* is the same, otherwise the member of the Fragment is added as a new instance to the target. If no *datasetId* is present, the default Attribute instance is targeted and merged if present and otherwise added. In case of a member *type* (of an Entity) in Entity Fragments, all included Entity Types are added, if they are not already contained in the *type* member of the target. -- For each member of the Fragment, whose value is an NGSI-LD Null, contained by the target, the target member is removed. In the case of deleting a specific Attribute instance with a *datasetId*, the handling shall be according to the description in [clause 5.6.5](10-tabapi-operation-definition.md#tabdelete-attribute). A *datasetId* cannot be deleted by setting it to the [value "urn:ngsi-ld:null"]{.HTML_Code}. -::: - -::: EX -EXAMPLE 1: - -Given an Entity containing the following *Property* : - -``` json -{ -  "temperature": { -    "type" : "Property", -    "value" : 25, -    "unitCode": "CEL" -    "observedAt": "2022-03-14T01:59:26.535Z" -  } -} -``` - -``` json -{ -  "temperature": { -    "type" : "Property", -    "value" : 100, -    "observedAt": "2022-03-14T13:00:00.000Z" -  } -} -``` - -``` json -{ -  "temperature": { -    "type" : "Property", -    "value" : 100, -    "unitCode": "CEL", -    "observedAt": "2022-03-14T13:00:00.000Z" -  } -} -``` -::: - -::: EX -EXAMPLE 2: - -Given an Entity containing the following *Property* : - -``` json -{ -  "address": { -    "type" : "Property", -    "value" : { -          "street": "Straße des 17. Juni", -          "city": "Berlin", -          "country": "Germany" -    } -  } -} -``` - -``` json -{ -  "address": { -    "type" : "Property", -    "value" : { -          "street": "Pariser Platz", -          "country": "urn:ngsi-ld:null" -    } -  } -} -``` - -``` json -{ -  "address": { -    "type" : "Property", -    "value": { -          "street": "Pariser Platz", -          "city": "Berlin" -    } -} -``` -::: - -### 5.5.13 Limiting operations to local scope {#tablimiting-operations-to-local-scope number="10.5.13"} - -The API provides a binding-specific mechanism to limit the execution of operations to a local scope, i.e. to only execute it based on information available in the [Context Source]{.HTML_Keyboard} or [Context Broker ]{.HTML_Keyboard}directly targeted by the request. This enables limiting cascading distributed operations [(clause 4.3.6.4](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations)) and, in some cases, also enables broader local operations, e.g. pertaining to **all** entities, which would be too expensive in the distributed case. - -The [localOnly ]{.HTML_Code}member in the *Subscription* [(clause 5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) requests that the subscription only matches Entities stored locally. - -The [localOnly]{.HTML_Code} member in the *RegistrationManagementInfo* (clause 5.2.34) of a [Context Source Registration]{.HTML_Keyboard} request that, when contacting the registered [Context]{.HTML_Keyboard}[Source]{.HTML_Keyboard}, a local scope shall be specified. Thus, the registered [Context Source]{.HTML_Keyboard} only provides its local information, not information from further [Context Sources]{.HTML_Keyboard} in its own [Context Registry]{.HTML_Keyboard}. - -If the request limits the execution of the operation to the local scope, [Context Source Registrations]{.HTML_Keyboard} from the [Context Registry]{.HTML_Keyboard} will not be used. - -Operations on a Snapshot (see [clause 5.5.15](10-tabapi-operation-definition.md#tabsnapshot-behaviour)) are always implicitly local scope, overriding setting a local scope to *false*, i.e. such a setting is to be ignored by implementations. - -### 5.5.14 Distributed Transactional Behaviour {#tabdistributed-transactional-behaviour number="10.5.14"} - -The following operations may occur as part of a distributed transactional request: - -::: B1plus -- Retrieve Entity [(clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)). -- Query Entities [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)). -- Retrieve Temporal Evolution of an Entity [(clause 5.7.3](10-tabapi-operation-definition.md#tabretrieve-temporal-evolution-of-an-entity)). -- Query Temporal Evolution of Entities [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)). -::: - -In the case that a client wishes to indicate to a Context Broker that a request is part of a unitary sequence of requests, the Context Broker shall create and cache an EntityMap for future use and should return the location of said EntityMap in a specific field. The caching strategy and expiry time shall take into account a suggested expiry time, if present, and depend on implementation specific configurations. Context Sources should indicate that they do not support EntityMaps, through declining to return the location of an EntityMap when requested to do so. - -If a subsequent request references an existent EntityMap, it shall be used for the purposes of Entity registration matching, and queries shall be filtered to only consider the Entities listed. Subsequent requests referencing an EntityMap shall use the same parameters as in the original request that created the EntityMap, except for the specification of Entity identifiers or parameters related to pagination, or, in the case of temporal requests, the temporal query. If an EntityMap has expired, or cannot be accessed, no inference can be made as to which entities are held within the Context Sources and a new one shall be created. An EntityMap fixes the Entities to be considered for subsequent requests based on it. The creating Context Source shall remove Entities from the EntityMap that do not match the filters of the query at the time of processing. Other components shall only be allowed to update the expiry timestamp of the EntityMap, which can optionally be extended if the Context Sources implementation allows for it. - -### 5.5.15 Snapshot Behaviour {#tabsnapshot-behaviour number="10.5.15"} - -If a [Snapshot (see clause ]{.HTML_Keyboard}[4.3.7]{.HTML_Keyboard}[)]{.HTML_Keyboard} is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specific [Snapshot. Operations permitted on Snapshots are the same as those specified for the Core API and, if supported, the Temporal API (see Table ]{.HTML_Keyboard}[4.3.5-1]{.HTML_Keyboard}[). This means all operations are implicitly limited to a local scope with all relaxations allowing broader operations (see clause ]{.HTML_Keyboard}[5.5.13]{.HTML_Keyboard}[) and there is no need to explicitly set the local scope as a request parameter. ]{.HTML_Keyboard}The implicit limitation to local scope also means that [Context Source Registrations]{.HTML_Keyboard} from the [Context Registry]{.HTML_Keyboard} will not be used. - -[Snapshots]{.HTML_Keyboard} are explicitly created, and the [Snapshot ]{.HTML_Keyboard}identifier is provided on creation. How the [Snapshot ]{.HTML_Keyboard}identifier is specified for an API operation is protocol binding specific. - -The [Snapshot ]{.HTML_Keyboard}concept is orthogonal to the [Tenant]{.HTML_Keyboard} concept (see [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)). [Snapshots]{.HTML_Keyboard} can also be created on [Tenants]{.HTML_Keyboard}. To execute an operation on a Snapshot created on a [Tenant]{.HTML_Keyboard}, both [Snapshot]{.HTML_Keyboard} and [Tenant]{.HTML_Keyboard} (see [clause 5.5.10](10-tabapi-operation-definition.md#tabmulti-tenant-behaviour)) have to be specified for an API operation. - -If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be deleted, the [snapshotPriority]{.HTML_Code}, ranging from 1 (minimum) to 10 (maximum) with 5 being the default priority, should be considered. An implementation may also consider other aspects like the [expiresAt]{.HTML_Code}, or [lastUsedAt]{.HTML_Code} timestamp for such a decision. - -## 5.6 Context Information Provision {#tabcontext-information-provision number="10.6"} - -### 5.6.1 Create Entity {#tabcreate-entity number="10.6.1"} - -#### 5.6.1.1 Description {#tabdescription number="10.6.1.1"} - -This operation allows creating a new NGSI-LD Entity. - -#### 5.6.1.2 Use case diagram {#tabuse-case-diagram number="10.6.1.2"} - -A [Context Producer]{.HTML_Keyboard} can create an Entity within an NGSI-LD system as shown in [Figure 5.6.1.2‑1](10-tabapi-operation-definition.md#Figure_5.6.1.2-1). - -::: FL -![](./media/image16.png){style="width:3.48611in;height:2.91667in"} -::: - -::: {#Figure_5.6.1.2-1 .TF} -Figure 5.6.1.2-1: Create entity use case -::: - -#### 5.6.1.3 Input data {#tabinput-data number="10.6.1.3"} - -A JSON-LD document representing an NGSI-LD Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). - -#### 5.6.1.4 Behaviour {#tabbehaviour number="10.6.1.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If an **exclusive** [Context Source Registration]{.HTML_Keyboard} already exists for this Entity id (URI), Attributes from matching input data are forwarded for remote processing: -::: - -- ::: B2plus - For matching Registrations where the Create Entity operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this shall result in an error in case the complete create failed or in a partial success if some parts of the create succeeded. - ::: - -- ::: B2plus - For matching Registrations where the Create Entity operation is not supported, this shall result in an error of type *Conflict* if the complete Create Entity operation failed or in a partial success if some parts of it succeeded. - ::: - - ::: B1plus - The matching Attributes are then removed from the Fragment and not processed further. - ::: - -::: B1plus -- If any **redirect** [Context Source Registrations]{.HTML_Keyboard} exist that match against the input data, that input data is forwarded for remote processing by one or more matching endpoints: -::: - -::: B2plus -- For matching Registrations where the Create Entity operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in an error in case the complete create has failed or in a partial success if some parts of the create has succeeded. -- For matching **redirect** Registrations where the Create Entity operation is not supported, this shall result in an error of type *Conflict* if the complete Create Entity operation failed or in a partial success if some parts of it succeeded. -::: - -::: B1 -The matching Attributes are then removed from the Fragment and not processed further. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing by matching endpoints in case the Create Entity operation is supported. -- If the Entity already exists locally this shall result in an error of type *AlreadyExists*, if the complete Create Entity operation has failed or in a partial success if some parts of it has succeeded. -- Any remaining input data shall be used to create the Entity locally. -::: - -#### 5.6.1.5 Output data {#taboutput-data number="10.6.1.5"} - -A URI identifying the newly created Entity. - -### 5.6.2 Update Attributes {#tabupdate-attributes number="10.6.2"} - -#### 5.6.2.1 Description {#tabdescription-1 number="10.6.2.1"} - -This operation allows modifying an existing NGSI-LD Entity by updating **already existing** Attributes (Properties or Relationships) and by appending non-existing ones. - -#### 5.6.2.2 Use case diagram {#tabuse-case-diagram-1 number="10.6.2.2"} - -A [Context Producer]{.HTML_Keyboard} can update Attributes within an NGSI-LD system as shown in [Figure 5.6.2.2‑1](10-tabapi-operation-definition.md#Figure_5.6.2.2-1). - -::: FL -![](./media/image17.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.2.2-1 .TF} -Figure 5.6.2.2-1: Update Attributes use case -::: - -#### 5.6.2.3 Input data {#tabinput-data-1 number="10.6.2.3"} - -::: B1plus -- A URI representing the id of the Entity to be updated (target Entity). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- A JSON-LD document representing an NGSI-LD Entity Fragment. -::: - -#### 5.6.2.4 Behaviour {#tabbehaviour-1 number="10.6.2.4"} - -::: B1plus -- If the Entity ID is not present or it is not a valid URI then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent to the target entity held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), an error of type *ResourceNotFound* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type *OperationNotSupported* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, Attributes from matching input data are forwarded for remote processing. For each matching registration: -::: - -::: B2plus -- If the Update Attributes operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Update Attributes operation is not supported by the registration, this shall result in an error of type *Conflict* if the complete update failed or in a partial success if some parts of the update succeeded. -::: - -::: B1plus -- The matching Attributes are then removed from the Fragment and not processed further. -- If there are remaining Attributes, for any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints in case the Update Attributes operation is supported by the matched registration. -- Then, implementations shall perform a partial update patch operation over the remains of the target Entity as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour), using the following procedure. -- For each Attribute (Property or Relationship) included by the Entity Fragment at root level: -::: - -::: B2plus -- If the target Entity does not include a matching Attribute (considering term expansion rules as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)) then such Attribute shall be appended to the target Entity. -- If the target Entity already includes a matching Attribute (considering term expansion rules as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)): -::: - -::: B3plus -- If a *datasetId* is present in the Attribute included by the Entity Fragment: -::: - -::: B4 -- If an Attribute instance in the target Entity has the same*datasetIddatasetIdcreatedAt*[clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) -- If an Attribute instance in the target Entity has the same*datasetIddatasetId* -- Otherwise the Attribute instance with the specified*datasetId* -::: - -::: B3plus -- If no *datasetId* is present in the Attribute included by the Entity Fragment, the default Attribute instance is targeted: -::: - -::: B4 -- If the default Attribute instance is present and the Attribute value is not NGSI-LD Null*,createdAt*[clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) -- If the default Attribute instance is present and the Attribute value is NGSI-LD Null*,* -- Otherwise the default Attribute instance shall be appended to the target Entity. -::: - -::: B1plus -- If *type* is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity. -- If *scope* is included in the Fragment and the target entity includes *scope*, replace the scope by the one included in the Fragment, otherwise ignore it. -::: - -#### 5.6.2.5 Output data {#taboutput-data-1 number="10.6.2.5"} - -::: B1plus -- A status code indicating whether all the new Attributes were updated or only some of them. -- List of Attributes (Properties or Relationships) actually updated. -::: - -### 5.6.3 Append Attributes {#tabappend-attributes number="10.6.3"} - -#### 5.6.3.1 Description {#tabdescription-2 number="10.6.3.1"} - -This operation allows modifying an NGSI-LD Entity by adding new attributes (Properties or Relationships). - -#### 5.6.3.2 Use case diagram {#tabuse-case-diagram-2 number="10.6.3.2"} - -A [Context Producer]{.HTML_Keyboard} can append new Attributes to an existing Entity within an NGSI-LD system as shown in Figure 5.6.3.2-1. - -::: FL -![](./media/image18.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.3.2-1 .TF} -Figure 5.6.3.2-1: Append Attributes use case -::: - -#### 5.6.3.3 Input data {#tabinput-data-2 number="10.6.3.3"} - -::: B1plus -- A URI representing the id of the E to be modified (target Entity). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- A JSON-LD document representing an NGSI-LD Entity Fragment. -- An optional flag indicating whether overwriting existing Attributes within the append operation should be permitted or denied. By default, Attribute overwrites are permitted. -::: - -#### 5.6.3.4 Behaviour {#tabbehaviour-2 number="10.6.3.4"} - -The following behaviour shall be exhibited by compliant implementations: - -::: B1plus -- If the Entity ID is not present or it is not a valid URI then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about this Entity, because there is no existing Entity which id (URI), and where specified type, is equivalent held locally to the one passed as a parameter, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), an error of type *ResourceNotFound* shall be raised. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation*.* -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration: -::: - -::: B2plus -- If the Append Attributes operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Append Attributes operation is not supported by the registration, this shall result in an error of type *Conflict* if the complete append failed or in a partial success if some parts of the append succeeded. -::: - -::: B1plus -- The matching Attributes are then removed from the Fragment and not processed further. -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints in case the Append Attributes operation is supported. -- Then, implementations shall perform an Append Attributes operation over the remains of the target Entity as using the following procedure: -::: - -::: B2plus -- For each Attribute (Property or Relationship) included by the Entity Fragment at root level: -::: - -::: B3plus -- If a *datasetId* is present in the Attribute included by the Entity Fragment: -::: - -::: B4 -- If no Attribute instance of the same target Entity exists that has the same*datasetId* -- If an Attribute instance of the same target Entity exists that has the same*datasetId:* -- If overwrite is allowed, then the existing Attribute with the specified*datasetIdcreatedAt*[clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) -- If overwrite is not allowed, the existing Attribute with the specified*datasetId* -::: - -::: B3plus -- If no *datasetId* is present in the Attribute included by the Entity Fragment: -::: - -::: B4 -- If no default Attribute instance of the same target Entity exists, then such Attribute shall be appended to the target Entity. -- If a default Attribute instance of the same target Entity exists: -- If overwrite is allowed, then the existing default Attribute in the target Entity shall be replaced by the new one supplied. The system generated*createdAt*[clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) -- If overwrite is not allowed the existing default Attribute in the target Entity shall be left untouched. -::: - -::: B2plus -- If *type* is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity. -- If *scope* is included in the Fragment and overwrite is allowed, the scope of the target Entity will become the one included in the Fragment. Otherwise, the Scopes in the Fragment that are not part of the value of *scope* of the target Entity will be appended to the value of the *scope* of the target Entity. If there is more than one Scope, the value of *scope* is represented as a JSON array containing all Scopes. -::: - -#### 5.6.3.5 Output data {#taboutput-data-2 number="10.6.3.5"} - -::: B1plus -- A status code indicating whether all the new Attributes were appended or only some of them. -- List of Attributes (Properties and/or Relationships) actually appended. -::: - -### 5.6.4 Partial Attribute update {#tabpartial-attribute-update number="10.6.4"} - -#### 5.6.4.1 Description {#tabdescription-3 number="10.6.4.1"} - -This operation allows performing a **partial update on an NGSI-LD Entity's Attribute** (Property or Relationship). A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. This operation supports the deletion of sub-Attributes but not the deletion of the whole Attribute itself. - -#### 5.6.4.2 Use case diagram {#tabuse-case-diagram-3 number="10.6.4.2"} - -A [Context Producer]{.HTML_Keyboard} can carry out a partial Attribute update of an Entity within an NGSI-LD System as shown in Figure 5.6.4.2-1. - -::: FL -![](./media/image19.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.4.2-1 .TF} -Figure 5.6.4.2-1: Partial Attribute update use case -::: - -#### 5.6.4.3 Input data {#tabinput-data-3 number="10.6.4.3"} - -::: B1plus -- Entity ID (URI) of the concerned Entity, the target Entity. -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- Target Attribute (Property or Relationship) to be modified, identified by a name. -- A JSON-LD document representing an NGSI-LD Attribute Fragment. -::: - -#### 5.6.4.4 Behaviour {#tabbehaviour-3 number="10.6.4.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not valid or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute is *scope*, then an error of type *BadRequestData* shall be raised. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type *OperationNotSupported* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration: -::: - -- ::: B2plus - If the Partial Attribute update operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. - ::: - -- ::: B2plus - If the Partial Attribute update operation is not supported by the registration, this shall result in an error of type *Conflict* in case the complete partial Attribute update failed, or in a partial success if some parts of the partial Attribute update succeeded. - ::: - - ::: B1plus - No further processing is required. - ::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints in case the Partial Attribute update operation is supported. -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction), so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -- If the target Entity does not contain the target Attribute: -::: - -::: B2plus -- as a default instance in case no *datasetId* is present; -- as an instance with the specified *datasetId* if present; -::: - -::: B2 -then an error of type *ResourceNotFound* shall be raised. -::: - -::: B1plus -- Perform a partial update patch operation on the target Attribute following the algorithm mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour). If present in the provided NGSI-LD Entity Fragment, the type of the Attribute has to be the same as the type of the targeted Attribute fragment, i.e. it is not allowed to change the type of an Attribute. -::: - -#### 5.6.4.5 Output data {#taboutput-data-3 number="10.6.4.5"} - -None. - -### 5.6.5 Delete Attribute {#tabdelete-attribute number="10.6.5"} - -#### 5.6.5.1 Description {#tabdescription-4 number="10.6.5.1"} - -This operation allows deleting an NGSI-LD Attribute (Property or Relationship). The Attribute itself and all its children shall be deleted. - -#### 5.6.5.2 Use case diagram {#tabuse-case-diagram-4 number="10.6.5.2"} - -A [Context Producer]{.HTML_Keyboard} can delete a specific Attribute within an NGSI-LD system as shown in [Figure 5.6.5.2‑1](10-tabapi-operation-definition.md#Figure_5.6.5.2-1). - -::: FL -![](./media/image20.png){style="width:3.45833in;height:2.83333in"} -::: - -::: {#Figure_5.6.5.2-1 .TF} -Figure 5.6.5.2-1: Delete Attribute use case -::: - -#### 5.6.5.3 Input data {#tabinput-data-4 number="10.6.5.3"} - -::: B1plus -- Entity ID (URI) of the concerned Entity, the target Entity. -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- Target Attribute (Property or Relationship) to be deleted, identified by a name. -- An optional parameter identifying the *datasetId* of the target Attribute instance to be deleted. Otherwise the default Attribute instance is targeted. -- An optional flag *deleteAll* indicating whether also all target Attribute instances with a *datasetId* are to be deleted. -- An optional JSON-LD *\@context*. -::: - -#### 5.6.5.4 Behaviour {#tabbehaviour-4 number="10.6.5.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not a valid name or it is not present, then an error of type *BadRequestData* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the Delete Attribute operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Delete Attribute update operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete delete Attribute failed, or in a partial success if some parts of the delete Attribute succeeded. -::: - -::: B2 -No further processing is required. -::: - -::: B1plus -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints in case the Delete Attribute operation is supported by the matched registration. -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -- If the target Entity does not contain the target Attribute then an error of type *ResourceNotFound* shall be raised. -- If the target Attribute is *scope*, remove the *scope* Attribute from the target Entity. -- If the *deleteAll* flag is set, remove all target Attribute instances from the target Entity. -- Otherwise: -::: - -::: B2plus -- if a *datasetId* parameter is provided, remove only the target Attribute instance from the given dataset whose *datasetId* matches the parameter; -- if no *datasetId* parameter is provided, remove the default target Attribute instance from the target Entity. -::: - -#### 5.6.5.5 Output data {#taboutput-data-4 number="10.6.5.5"} - -None. - -### 5.6.6 Delete Entity {#tabdelete-entity number="10.6.6"} - -#### 5.6.6.1 Description {#tabdescription-5 number="10.6.6.1"} - -This operation allows deleting an NGSI-LD Entity. - -#### 5.6.6.2 Use case diagram {#tabuse-case-diagram-5 number="10.6.6.2"} - -A [Context Producer]{.HTML_Keyboard} can completely delete an Entity within an NGSI-LD system as shown in [Figure 5.6.6.2‑1](10-tabapi-operation-definition.md#Figure_5.6.6.2-1). - -::: FL -![](./media/image21.png){style="width:3.45833in;height:2.83333in"} -::: - -::: {#Figure_5.6.6.2-1 .TF} -Figure 5.6.6.2-1: Delete Entity use case -::: - -#### 5.6.6.3 Input data {#tabinput-data-5 number="10.6.6.3"} - -::: B1plus -- Entity ID (URI) of the Entity to be deleted, the target Entity. -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -::: - -#### 5.6.6.4 Behaviour {#tabbehaviour-5 number="10.6.6.4"} - -::: B1plus -- If the target Entity ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the id, the request is forwarded for remote processing. For each matching registration: -::: - -::: B2plus -- If the Delete Entity operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), the request is forwarded to the Registration endpoint. -- If the Delete Entity update operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete delete Entity failed, or in a partial success if some parts of the delete Entity succeeded. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded in the case the Delete Entity operation is supported for remote processing by matching endpoints. -- The input data shall be used to remove the entity locally if it exists. -::: - -#### 5.6.6.5 Output data {#taboutput-data-5 number="10.6.6.5"} - -None. - -### 5.6.7 Batch Entity Creation {#tabbatch-entity-creation number="10.6.7"} - -#### 5.6.7.1 Description {#tabdescription-6 number="10.6.7.1"} - -This operation allows creating a batch of NGSI-LD Entities. - -#### 5.6.7.2 Use case diagram {#tabuse-case-diagram-6 number="10.6.7.2"} - -A [Context Producer]{.HTML_Keyboard} can create a batch of NGSI-LD Entities within an NGSI-LD system as shown in [Figure 5.6.7.2‑1](10-tabapi-operation-definition.md#Figure_5.6.7.2-1). - -::: FL -![](./media/image22.png){style="width:3.48611in;height:3.11111in"} -::: - -::: {#Figure_5.6.7.2-1 .TF} -Figure 5.6.7.2-1: Create a batch of Entities use case -::: - -#### 5.6.7.3 Input data {#tabinput-data-6 number="10.6.7.3"} - -::: B1plus -- A JSON-LD Array containing one or more JSON-LD documents each one representing an NGSI-LD Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). See [clause 5.5.11.1](10-tabapi-operation-definition.md#tabbatch-entity-creation-case) for information on behaviour when there is more than one instance of the same entity in the input Array. -::: - -#### 5.6.7.4 Behaviour {#tabbehaviour-6 number="10.6.7.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- If the input Array is empty or contains a *null* value in any of its items an error of type *BadRequestData* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity successfully created. S shall be initialized to the empty array. -- Let E be an array which shall contain a list of *BatchEntityError* as defined by [clause 5.2.17](10-tabapi-operation-definition.md#tabbatchentityerror), one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array. -- For each [Context Source Registration]{.HTML_Keyboard} CSR in the [Context Registry]{.HTML_Keyboard}: -::: - -::: B2plus -- Let IN be a copy of the original input array. -- Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **exclusive** [Context Source Registration]{.HTML_Keyboard}, which is not CSR itself. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **redirect** [Context Source Registration]{.HTML_Keyboard}, unless CSR is a redirect [Context Source Registration]{.HTML_Keyboard} itself. -- If IN is empty, continue with the next [Context Source Registration]{.HTML_Keyboard} if there is any. -- If the Batch Entity Creation operation is supported by CSR: -::: - -::: B3plus -- Forward the Batch Entity Creation request with IN as input Array. -- Merge the returned list of Entities successfully created with S. -- Merge the returned list of Entities in Error with E. -::: - -::: B2plus -- Otherwise, if the Create Entity operation [(clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity)) is supported by CSR: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward a Create Entity request for Entity EN. -- Merge any successful result(s) for Entity EN created with S. -- Merge any error result(s) for Entity EN created with E. -::: - -::: B2plus -- Otherwise: -::: - -::: B3plus -- In case CSR is an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard}, add an Error of type *Conflict* for each Entity in IN to E. -::: - -::: B1plus -- For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by [clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity), but limited to a local operation, as follows: -::: - -::: B2plus -- If the Entity was successfully created, then add the corresponding Entity ID to the S array. -- If the Entity creation failed, then a new *BatchEntityError* shall be added to E containing the failed Entity ID and the related *ProblemDetails*. -::: - -#### 5.6.7.5 Output data {#taboutput-data-6 number="10.6.7.5"} - -::: B1plus -- The list of Entities successfully created (S Array), if all Entities were created correctly; or -- the list of Entities successfully created (S Array) and the list of Entities in error (E Array), if only some or none of the Entities were created. -::: - -### 5.6.8 Batch Entity Creation or Update (Upsert) {#tabbatch-entity-creation-or-update-upsert number="10.6.8"} - -#### 5.6.8.1 Description {#tabdescription-7 number="10.6.8.1"} - -This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed. In some database jargon this kind of operation is known as "upsert". - -#### 5.6.8.2 Use case diagram {#tabuse-case-diagram-7 number="10.6.8.2"} - -A [Context Producer]{.HTML_Keyboard} can create or update a batch of Entities within an NGSI-LD system as shown in [Figure 5.6.8.2‑1](10-tabapi-operation-definition.md#Figure_5.6.8.2-1). - -::: FL -![](./media/image23.png){style="width:3.48611in;height:3.11111in"} -::: - -::: {#Figure_5.6.8.2-1 .TF} -Figure 5.6.8.2-1: Upsert a batch of Entities use case -::: - -#### 5.6.8.3 Input data {#tabinput-data-7 number="10.6.8.3"} - -::: B1plus -- A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). See [clause 5.5.11.2](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert-case) for information on behaviour when there is more than one instance of the same entity in the input Array. -- An optional flag indicating the update mode (only applies in case the Entity already exists): -::: - -::: B2plus -- Replace. All the existing Entity content shall be replaced (default mode). -- Update. Existing Entity content shall be updated. -::: - -#### 5.6.8.4 Behaviour {#tabbehaviour-7 number="10.6.8.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- If the input Array is empty or contains a *null* value in any of its items, an error of type *BadRequestData* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized to the empty array. -- Let E be an array which shall contain a list of *BatchEntityError* as defined by [clause 5.2.17](10-tabapi-operation-definition.md#tabbatchentityerror), one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array. -- For each [Context Source Registration]{.HTML_Keyboard} CSR in the [Context Registry]{.HTML_Keyboard}: -::: - -::: B2plus -- Let IN be a copy of the original input array. -- Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **exclusive** [Context Source Registration]{.HTML_Keyboard}, which is not CSR itself. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **redirect** [Context Source Registration]{.HTML_Keyboard}, unless CSR is a redirect [Context Source Registration]{.HTML_Keyboard} itself. -- If IN is empty, continue with the next [Context Source Registration]{.HTML_Keyboard} if there is any. -- If the Batch Entity Creation or Update (Upsert) operation is supported by CSR: -::: - -::: B3plus -- Forward the Batch Entity Creation or Update (Upsert) request with IN as input Array. -- Merge the returned list of Entities successfully created with S. -- Merge the returned list of Entities in Error with E. -::: - -::: B2plus -- Otherwise, if the Create Entity operation [(clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity)) is supported by CSR: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward a Create Entity request for Entity EN. -- If an error of type*AlreadyExists* -- If the Replace Entity operation[(clause 5.6.18](10-tabapi-operation-definition.md#tabreplace-entity)*Replace* -- Otherwise, if the Update Attributes operation[(clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes)*Update* -- Otherwise add an*OperationNotSupported* -::: - -::: B3plus -- Merge any successful result(s) for Entity EN created or updated with S. -- Merge any error result(s) for Entity EN created or updated with E. -::: - -::: B2plus -- Otherwise, if the Replace Entity operation [(clause 5.6.18](10-tabapi-operation-definition.md#tabreplace-entity)) is supported by CSR and the value of the update mode flag is *Replace* or the flag is not set: -::: - -::: B3plus -- Forward a Replace Entity request for Entity EN. -- Merge any successful result(s) for Entity EN updated with S. -- Merge any error result(s) for Entity EN updated with E. -::: - -::: B2plus -- Otherwise, if the Update Attributes operation [(clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes)) is supported by CSR and the value of the update mode flag is *Update*: -::: - -::: B3plus -- Forward an Update Attributes request for Entity EN. -- Merge any successful result(s) for Entity EN updated with S. -- Merge any error result(s) for Entity EN updated with E. -::: - -::: B2plus -- Otherwise: -::: - -::: B3plus -- In case CSR is an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard}, add an Error of type *Conflict* for each Entity in IN to E. -::: - -::: B1plus -- For each of the NGSI-LD Entities included in the input Array implementations shall: -::: - -::: B2plus -- Create the Entity locally if it does not exist (i.e. no Entity with the same Entity ID is present) executing the behaviour defined by [clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity), but limited to a local operation. -- If there were an existing Entity with the same Entity ID, it shall be completely replaced by the new Entity content provided, if the requested update mode is 'replace'. -- If there were an existing Entity with the same Entity ID, the behaviour defined by [clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes) shall be executed, but limited to a local operation, if the requested update mode is ["update"]{.HTML_Code}. -::: - -::: B1plus -- If successful, the local creation or update shall be added to S. If while processing an Entity there is any kind of error or abnormal situation, a *BatchEntityError* shall be added to E containing the failed Entity ID and the related *ProblemDetails*. -::: - -#### 5.6.8.5 Output data {#taboutput-data-7 number="10.6.8.5"} - -::: B1plus -- none (if all Entities already existed and are successfully updated); or -- the list of Entities successfully created (S Array), if all Entities not existing prior to this request have been successfully created and the others have been successfully updated; or -- the list of Entities successfully created or updated (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully created or updated. -::: - -### 5.6.9 Batch Entity Update {#tabbatch-entity-update number="10.6.9"} - -#### 5.6.9.1 Description {#tabdescription-8 number="10.6.9.1"} - -This operation allows updating a batch of NGSI-LD Entities. - -#### 5.6.9.2 Use case diagram {#tabuse-case-diagram-8 number="10.6.9.2"} - -A [Context Producer]{.HTML_Keyboard} can update a batch of Entities within an NGSI-LD system as shown in [Figure 5.6.9.2‑1](10-tabapi-operation-definition.md#Figure_5.6.9.2-1). - -::: FL -![](./media/image24.png){style="width:3.48611in;height:3.11111in"} -::: - -::: {#Figure_5.6.9.2-1 .TF} -Figure 5.6.9.2-1: Update a batch of Entities use case -::: - -#### 5.6.9.3 Input data {#tabinput-data-8 number="10.6.9.3"} - -::: B1plus -- A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). See [clause 5.5.11.3](10-tabapi-operation-definition.md#tabbatch-entity-update-case) for information on behaviour when there is more than one instance of the same entity in the input Array. -- An optional flag indicating whether Attributes shall be overwritten or not. By default, Attributes will be overwritten. -::: - -#### 5.6.9.4 Behaviour {#tabbehaviour-8 number="10.6.9.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- If the input Array is empty or contains a *null* value in any of its items, an error of type *BadRequestData* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized as the empty array. -- Let E be an array which shall contain a list of *BatchEntityError* as defined by [clause 5.2.17](10-tabapi-operation-definition.md#tabbatchentityerror), one for each NGSI-LD Entity which resulted in error. E shall be initialized as the empty array. -- For each [Context Source Registration]{.HTML_Keyboard} CSR in the [Context Registry]{.HTML_Keyboard}: -::: - -::: B2plus -- Let IN be a copy of the original input array. -- Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **exclusive** [Context Source Registration]{.HTML_Keyboard}, which is not CSR itself. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **redirect** [Context Source Registration]{.HTML_Keyboard}, unless CSR is a redirect [Context Source Registration]{.HTML_Keyboard} itself. -- Remove all Entities without Attributes from IN. -- If IN is empty, continue with the next [Context Source Registration]{.HTML_Keyboard} if there is any. -- If the Batch Entity Update operation is supported by CSR: -::: - -::: B3plus -- Forward the Batch Entity Update request with IN as input Array. -- Merge the returned list of Entities successfully created with S. -- Merge the returned list of Entities in Error with E. -::: - -::: B2plus -- Otherwise, if the Update Attributes operation [(clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes)) is supported by CSR and Attribute overwrite is permitted: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward an Update Attributes request for Entity EN. -- Merge any successful result(s) for Entity EN updated with S. -- Merge any error result(s) for Entity EN updated with E. -::: - -::: B2plus -- Otherwise, if the Append Attributes operation [(clause 5.6.3](10-tabapi-operation-definition.md#tabappend-attributes)) is supported by CSR and Attribute overwrite is not permitted: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward an Append Attributes request for Entity EN with Attribute overwrite disabled: -- Merge any successful result(s) for Entity EN updated with S. -- Merge any error result(s) for Entity EN updated with E. -::: - -::: B2plus -- Otherwise: -::: - -::: B3plus -- In case CSR is an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard}, add an Error of type *Conflict* for each Entity in IN to E. -::: - -::: B1plus -- For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by [clause 5.6.3](10-tabapi-operation-definition.md#tabappend-attributes), but limited to a local operation, as follows: -::: - -::: B2plus -- If the Entity was successfully updated (Attributes appended), then add the corresponding Entity ID to the S array. -- If the Entity update failed, then a new *BatchEntityError* shall be added to E containing the failed Entity ID and the *ProblemDetails* associated. -::: - -#### 5.6.9.5 Output data {#taboutput-data-8 number="10.6.9.5"} - -::: B1plus -- none (if all Entities are successfully updated); or -- the list of Entities successfully updated (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully updated. -::: - -### 5.6.10 Batch Entity Delete {#tabbatch-entity-delete number="10.6.10"} - -#### 5.6.10.1 Description {#tabdescription-9 number="10.6.10.1"} - -This operation allows deleting a batch of NGSI-LD Entities. - -#### 5.6.10.2 Use case diagram {#tabuse-case-diagram-9 number="10.6.10.2"} - -A [Context Producer]{.HTML_Keyboard} can delete a batch of Entities within an NGSI-LD system as shown in [Figure 5.6.10.2‑1](10-tabapi-operation-definition.md#Figure_5.6.10.2-1). - -::: FL -![](./media/image25.png){style="width:3.45833in;height:3.08333in"} -::: - -::: {#Figure_5.6.10.2-1 .TF} -Figure 5.6.10.2-1: Delete a batch of Entities use case -::: - -#### 5.6.10.3 Input data {#tabinput-data-9 number="10.6.10.3"} - -::: B1plus -- A JSON-LD Array containing a list of Entity IDs (URIs) that are requested to be deleted. See [clause 5.5.11.4](10-tabapi-operation-definition.md#tabbatch-entity-delete-case) for information on behaviour when there is more than one instance of the same Entity ID in the input Array. -::: - -#### 5.6.10.4 Behaviour {#tabbehaviour-9 number="10.6.10.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- If the input Array is empty or contains a *null* value in any of its items, an error of type *BadRequestData* shall be raised. -- Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized to the empty array. -- Let E be an array which shall contain a list of *BatchEntityError* as defined by [clause 5.2.17](10-tabapi-operation-definition.md#tabbatchentityerror), one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array. -- For each [Context Source Registration]{.HTML_Keyboard} CSR in the [Context Registry]{.HTML_Keyboard}: -::: - -::: B2plus -- Let IN be a copy of the original input array. -- Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **exclusive** [Context Source Registration]{.HTML_Keyboard}, which is not CSR itself. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **redirect** [Context Source Registration]{.HTML_Keyboard}, unless CSR is a redirect [Context Source Registration]{.HTML_Keyboard} itself. -- Remove all Entities without Attributes from IN. -- If IN is empty, continue with the next [Context Source Registration]{.HTML_Keyboard} if there is any. -- If the Batch Entity Delete operation is supported by CSR: -::: - -::: B3plus -- Forward the Batch Entity Delete request with IN as input Array. -- Merge the returned list of Entities successfully created with S. -- Merge the returned list of Entities in Error with E. -::: - -::: B2plus -- Otherwise, if the Delete Entity operation [(clause 5.6.6](10-tabapi-operation-definition.md#tabdelete-entity)) is supported by CSR: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward a Delete Entity request for Entity EN. -- Merge any successful result(s) for Entity EN deleted with S. -- Merge any error result(s) for Entity EN deleted with E. -::: - -::: B2plus -- Otherwise: -::: - -::: B3plus -- In case CSR is an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard}, add an Error of type *Conflict* for each Entity in IN to E. -- For each of the NGSI-LD Entity IDs included in the input Array execute the behaviour defined by [clause 5.6.6](10-tabapi-operation-definition.md#tabdelete-entity), but limited to a local operation, as follows: -::: - -::: B4 -- If the Entity corresponding to an Entity ID was successfully deleted, then add such Entity ID to the S array. -- If the Entity deletion failed, then a new*BatchEntityErrorProblemDetails* -::: - -#### 5.6.10.5 Output data {#taboutput-data-9 number="10.6.10.5"} - -::: B1plus -- none (if all Entities that already existed are successfully deleted); or -- the list of Entities successfully deleted (S Array), and the list of Entities in error (E Array), if some or all of the Entities have not been successfully deleted. -::: - -### 5.6.11 Create or Update (Upsert) Temporal Evolution of an Entity {#tabcreate-or-update-upsert-temporal-evolution-of-an-entity number="10.6.11"} - -#### 5.6.11.1 Description {#tabdescription-10 number="10.6.11.1"} - -This operation allows creating or updating (by adding new Attribute instances) the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -#### 5.6.11.2 Use case diagram {#tabuse-case-diagram-10 number="10.6.11.2"} - -A [Context Producer]{.HTML_Keyboard} can create the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} within an NGSI-LD system as shown in Figure 5.6.11.2-1. - -Similarly, if the Entity already exists then an Update scenario will be in place. - -::: FL -![](./media/image26.png){style="width:3.48611in;height:2.91667in"} -::: - -::: {#Figure_5.6.11.2-1 .TF} -Figure 5.6.11.2-1: Create or Update (Upsert) Temporal Evolution of an Entity use case -::: - -#### 5.6.11.3 Input data {#tabinput-data-10 number="10.6.11.3"} - -A JSON-LD document representing the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} as mandated by [clause 5.2.20](10-tabapi-operation-definition.md#tabentitytemporal). - -#### 5.6.11.4 Behaviour {#tabbehaviour-10 number="10.6.11.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If an **exclusive** [Context Source Registration]{.HTML_Keyboard} already exists for this Entity id (URI), Attributes from matching input data are forwarded for remote processing: -::: - -- ::: B2plus - For matching Registrations where the "Create or Update (Upsert) Temporal Evolution of an Entity" operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this shall result in an error in case the complete "Create or Update (Upsert) Temporal Evolution of an Entity" operation failed or in a partial success if some parts of it succeeded. - ::: - -- ::: B2plus - For matching Registrations where the "Create Entity" operation is not supported, this shall result in an error of type *Conflict* in case the complete "Create or Update (Upsert) Temporal Evolution of an Entity" operation failed or in a partial success if some parts of it succeeded. - ::: - - ::: B1plus - The matching Attributes are then removed from the Fragment and not processed further. - ::: - -::: B1plus -- If any **redirect** [Context Source Registrations]{.HTML_Keyboard} exist that match against the input data, that input data is forwarded for remote processing by one or more matching endpoints: -::: - -::: B2plus -- For matching Registrations where the "Create or Update (Upsert) Temporal Evolution of an Entity" operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in an error in case the complete "Create or Update (Upsert) Temporal Evolution of an Entity" operation failed or in a partial success if some parts of it succeeded. -- For matching **redirect** Registrations where the "Create or Update (Upsert) Temporal Evolution of an Entity" operation is not supported, this shall result in an error of type *Conflict* in case the complete "Create or Update (Upsert) Temporal Evolution of an Entity" operation failed or in a partial success if some parts of it succeeded. -::: - -::: B1 -The matching Attributes are then removed from the Fragment and not processed further. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing by matching endpoints. -- If the NGSI-LD endpoint already knows about this [Temporal Evolution of an Entity]{.HTML_Keyboard}, because there is an existing [Temporal Evolution of an Entity]{.HTML_Keyboard} whose id (URI) is the same, then all the Attribute instances included by the Temporal Evolution shall be added to the existing Entity as mandated by [clause 5.6.12](10-tabapi-operation-definition.md#tabadd-attributes-to-temporal-evolution-of-an-entity). If *type* is included in the EntityTemporal Fragment and it includes Entity Type names that are not yet in the target [Temporal Evolution of an Entity,]{.HTML_Keyboard} add them to the list of Entity Type names of the target [Temporal Evolution of anEntity]{.HTML_Keyboard}. -- Otherwise, implementations shall create the provided [Temporal Evolution of an Entity]{.HTML_Keyboard}. -::: - -#### 5.6.11.5 Output data {#taboutput-data-10 number="10.6.11.5"} - -On creation, a URI identifying the newly created Temporal Evolution of an Entity. None otherwise. - -### 5.6.12 Add Attributes to Temporal Evolution of an Entity {#tabadd-attributes-to-temporal-evolution-of-an-entity number="10.6.12"} - -#### 5.6.12.1 Description {#tabdescription-11 number="10.6.12.1"} - -This operation allows modifying the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} by adding new Attribute instances. - -#### 5.6.12.2 Use case diagram {#tabuse-case-diagram-11 number="10.6.12.2"} - -A [Context Producer]{.HTML_Keyboard} can add new Attributes or Attribute instances to an existing [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} within an NGSI-LD system as shown in [Figure 5.6.12.2‑1](10-tabapi-operation-definition.md#Figure_5.6.12.2-1). - -::: FL -![](./media/image27.png){style="width:3.48611in;height:2.95833in"} -::: - -::: {#Figure_5.6.12.2-1 .TF} -Figure 5.6.12.2-1: Add Attributes to Temporal Evolution of an Entity use case -::: - -#### 5.6.12.3 Input data {#tabinput-data-11 number="10.6.12.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolution of an Entity]{.HTML_Keyboard} to be modified with additional Attributes. -- A JSON-LD document representing an NGSI-LD Fragment of *EntityTemporal*, including only the new Attribute instance(s), and contained by an Array. -::: - -#### 5.6.12.4 Behaviour {#tabbehaviour-11 number="10.6.12.4"} - -The following behaviour shall be exhibited by compliant implementations: - -::: B1plus -- If the Entity ID is not present or it is not a valid URI then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target [Temporal Evolution of an Entity]{.HTML_Keyboard}, because there is no existing [Temporal Evolution of an Entity]{.HTML_Keyboard} whose id (URI) is equivalent to the one passed as a parameter held locally and no matching registrations apply, an error of type *ResourceNotFound* shall be raised. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration: -::: - -::: B2plus -- If the "Add Attributes to Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. -- If the "Add Attributes to Temporal Evolution of an Entity" operation is not supported by the matched registration, this shall result in an error of type *Conflict* if the complete "Add Attributes to Temporal Evolution of an Entity"operation failed or in a partial success if some parts of it succeeded. -::: - -::: B1 -The matching Attributes are then removed from the Fragment and not processed further. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} exists locally and matches against the remaining input data, implementations shall do the following: -::: - -::: B2plus -- For each Attribute (Property or Relationship) instance included by the *EntityTemporal* Fragment at root level: -::: - -::: B3plus -- The Attribute (considering term expansion rules as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)) instance(s) shall be added to the target [Temporal Evolution of an Entity]{.HTML_Keyboard}. -::: - -::: B1plus -- If *type* is included in the EntityTemporal Fragment and it includes Entity Type names that are not yet in the target [Temporal Evolution of an Entity]{.HTML_Keyboard}, add them to the list of Entity Type names of the target [Temporal Evolution of theEntity]{.HTML_Keyboard}. -::: - -#### 5.6.12.5 Output data {#taboutput-data-11 number="10.6.12.5"} - -None. - -### 5.6.13 Delete Attribute from Temporal Evolution of an Entity {#tabdelete-attribute-from-temporal-evolution-of-an-entity number="10.6.13"} - -#### 5.6.13.1 Description {#tabdescription-12 number="10.6.13.1"} - -This operation allows deleting an Attribute (Property or Relationship) of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. The Attribute itself and all its child NGSI-LD elements shall be deleted. - -#### 5.6.13.2 Use case diagram {#tabuse-case-diagram-12 number="10.6.13.2"} - -A [Context Producer]{.HTML_Keyboard} can delete a specific Attribute of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} within an NGSI-LD system as shown in [Figure 5.6.13.2‑1](10-tabapi-operation-definition.md#Figure_5.6.13.2-1). - -::: FL -![](./media/image28.png){style="width:3.66667in;height:2.86111in"} -::: - -::: {#Figure_5.6.13.2-1 .TF} -Figure 5.6.13.2-1: Delete Attribute from Temporal Evolution of an Entity use case -::: - -#### 5.6.13.3 Input data {#tabinput-data-12 number="10.6.13.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolution of an Entity]{.HTML_Keyboard} to be modified by removing the target Attribute. -- Target Attribute (Property or Relationship) to be deleted, identified by a name. -- An optional parameter identifying the dataset (*datasetId*) of the target Attribute instance to be deleted. -- An optional parameter, a flag, (*deleteAll*) indicating whether all target Attribute instances are to be deleted, regardless of *datasetId*. -- An optional JSON-LD *\@context*. -::: - -#### 5.6.13.4 Behaviour {#tabbehaviour-12 number="10.6.13.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not a valid name, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing [Temporal Evolution of an Entity]{.HTML_Keyboard} whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the "Delete Attribute from Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. -- If the "Delete Attribute from Temporal Evolution of an Entity" operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete "Delete Attribute from Temporal Evolution of an Entity" failed, or in a partial success if some parts of it succeeded. -::: - -::: B1 -No further processing is required. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} exists locally, implementations shall do the following: -::: - -::: B2plus -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} does not contain the target Attribute then an error of type *ResourceNotFound* shall be raised. -- If the *deleteAll* flag is set, remove all target Attribute instances from the target Entity. -::: - -::: B1plus -- Otherwise: -::: - -::: B2plus -- if a *datasetId* parameter is provided, remove only any target Attribute instance from the given dataset; -- if no *datasetId* parameter is provided, remove only the default target Attribute instance *datasetId* from the target Entity. -::: - -#### 5.6.13.5 Output data {#taboutput-data-12 number="10.6.13.5"} - -None. - -### 5.6.14 Modify Attribute instance in Temporal Evolution of an Entity {#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity number="10.6.14"} - -#### 5.6.14.1 Description {#tabdescription-13 number="10.6.14.1"} - -This operation allows modifying a specific Attribute (Property or Relationship) instance, identified by its *instanceId*, of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -This operation enables the correction of wrong information that could have been previously added to the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -#### 5.6.14.2 Use case diagram {#tabuse-case-diagram-13 number="10.6.14.2"} - -A [Context Producer]{.HTML_Keyboard} can modify a specific Attribute instance, identified by a given *instanceId*, of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity ]{.HTML_Keyboard}within an NGSI-LD system as shown in [Figure 5.6.14.2‑1](10-tabapi-operation-definition.md#Figure_5.6.14.2-1). - -::: FL -![](./media/image29.png){style="width:3.76389in;height:3.01389in"} -::: - -::: {#Figure_5.6.14.2-1 .TF} -Figure 5.6.14.2-1: Modify Attribute Instance in Temporal Evolution of an Entity use case -::: - -#### 5.6.14.3 Input data {#tabinput-data-13 number="10.6.14.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolution of an Entity]{.HTML_Keyboard} to be modified by changing an instance of the target Attribute. -- Target Attribute (Property or Relationship) to be modified, identified by a name. -- Attribute instance to be modified, identified by its *instanceId*. -- A JSON-LD document representing an NGSI-LD Fragment of *EntityTemporal*, including only the new Attribute instance, contained by an Array of exactly one item. -- An optional JSON-LD \@context. -::: - -#### 5.6.14.4 Behaviour {#tabbehaviour-13 number="10.6.14.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not a valid name or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target *instanceId* is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the "Modify Attribute instance in Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. -- If the "Modify Attribute instance in Temporal Evolution of an Entity" operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete Modify Attribute instance in [Temporal Evolution of an Entity]{.HTML_Keyboard} operation failed, or in a partial success if some parts of it succeeded. -::: - -::: B2 -No further processing is required. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} exists locally, implementations shall do the following: -::: - -::: B2plus -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} does not contain the target Attribute then an error of type *ResourceNotFound* shall be raised. -- If for the target Attribute no instance with the specified *instanceId* exists, an error of type *ResourceNotFound* shall be raised. -::: - -::: B1plus -- Replace the target Attribute instance identified by the *instanceId* with the Attribute instance in the *EntityTemporal* Fragment. The *createdAt* property of the concerned instance shall remain unchanged, but the *modifiedAt* property shall be set to the timestamp corresponding to this modification. -::: - -#### 5.6.14.5 Output data {#taboutput-data-13 number="10.6.14.5"} - -None. - -### 5.6.15 Delete Attribute instance from Temporal Evolution of an Entity {#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity number="10.6.15"} - -#### 5.6.15.1 Description {#tabdescription-14 number="10.6.15.1"} - -This operation allows deleting one Attribute instance (Property or Relationship), identified by its *instanceId*, of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. The Attribute itself and all its child elements shall be deleted. This operation enables the removal of individual Attribute instances that could have been previously added to the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -#### 5.6.15.2 Use case diagram {#tabuse-case-diagram-14 number="10.6.15.2"} - -A [Context Producer]{.HTML_Keyboard} can delete an Attribute instance, identified by a given *instanceId*, of the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} within an NGSI-LD system as shown in [Figure 5.6.15.2‑1](10-tabapi-operation-definition.md#Figure_5.6.15.2-1). - -::: FL -![](./media/image30.png){style="width:3.76389in;height:2.86111in"} -::: - -::: {#Figure_5.6.15.2-1 .TF} -Figure 5.6.15.2-1: Delete Attribute Instance from Temporal Evolution of an Entity use case -::: - -#### 5.6.15.3 Input data {#tabinput-data-14 number="10.6.15.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolutionof an Entity]{.HTML_Keyboard} to be modified by deleting an instance of the target Attribute. -- Target Attribute (Property or Relationship) to be deleted, identified by a name. -- Attribute instance to be deleted, identified by its *instanceId*. -- An optional JSON-LD *\@context*. -::: - -#### 5.6.15.4 Behaviour {#tabbehaviour-14 number="10.6.15.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not a valid name or it is not present, then an error of type *BadRequestData* shall be raised. -- If the target *instanceId* is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the "Delete Attribute instance from Temporal Evolution of an Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. -- If the "Delete Attribute instance from Temporal Evolution of an Entity" operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete "Delete Attribute instance from Temporal Evolution of an Entity" failed, or in a partial success if some parts of it succeeded. -::: - -::: B1 -No further processing is required. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} exists locally, implementations shall do the following: -::: - -::: B2plus -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -::: - -::: B1plus -- If the target [Temporal Evolution of the Entity]{.HTML_Keyboard} does not contain the target Attribute then an error of type *ResourceNotFound* shall be raised. -- If for the target Attribute no instance with the specified *instanceId* exists, an error of type *ResourceNotFound* shall be raised. -- Remove the instance, with the specified *instanceId,* of the target Attribute from the target Entity. -::: - -#### 5.6.15.5 Output data {#taboutput-data-14 number="10.6.15.5"} - -None. - -### 5.6.16 Delete Temporal Evolution of an Entity {#tabdelete-temporal-evolution-of-an-entity number="10.6.16"} - -#### 5.6.16.1 Description {#tabdescription-15 number="10.6.16.1"} - -This operation allows deleting the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -#### 5.6.16.2 Use case diagram {#tabuse-case-diagram-15 number="10.6.16.2"} - -A [Context Producer]{.HTML_Keyboard} can completely delete the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} within an NGSI-LD system as shown in [Figure 5.6.16.2‑1](10-tabapi-operation-definition.md#Figure_5.6.16.2-1). - -::: FL -![](./media/image31.png){style="width:3.48611in;height:2.86111in"} -::: - -::: {#Figure_5.6.16.2-1 .TF} -Figure 5.6.16.2-1: Delete Temporal Evolution of an Entity use case -::: - -#### 5.6.16.3 Input data {#tabinput-data-15 number="10.6.16.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolution of an Entity]{.HTML_Keyboard} to be deleted. -::: - -#### 5.6.16.4 Behaviour {#tabbehaviour-15 number="10.6.16.4"} - -::: B1plus -- If the target Entity ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the "Delete Temporal Evolution of Entity" operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint. -- If the "Delete Temporal Evolution of Entity" operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete "Delete Temporal Evolution of Entity" failed, or in a partial success if some parts of it succeeded. -::: - -::: B1 -No further processing is required. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the input data, that input data is also forwarded for remote processing to matching endpoints. -- If the target [Temporal Evolution of an Entity]{.HTML_Keyboard} exists locally, the entire [Temporal Evolution of the Entity]{.HTML_Keyboard} shall be removed. -::: - -#### 5.6.16.5 Output data {#taboutput-data-15 number="10.6.16.5"} - -None. - -### 5.6.17 Merge Entity {#tabmerge-entity number="10.6.17"} - -#### 5.6.17.1 Description {#tabdescription-16 number="10.6.17.1"} - -This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch processing rules defined in IETF RFC 7396 [[16]](7-tabreferences.md#16) by adding new Attributes (Properties or Relationships) or modifying or deleting existing Attributes associated with an existing Entity. - -#### 5.6.17.2 Use case diagram {#tabuse-case-diagram-16 number="10.6.17.2"} - -A [Context Producer]{.HTML_Keyboard} can perform a merge on an Entity within an NGSI-LD system as shown in [Figure 5.6.17.2‑1](10-tabapi-operation-definition.md#Figure_5.6.17.2-1). - -::: FL -![](./media/image32.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.17.2-1 .TF} -Figure 5.6.17.2-1: Merge Entity use case -::: - -#### 5.6.17.3 Input data {#tabinput-data-16 number="10.6.17.3"} - -::: B1plus -- A URI representing the id of the Entity to be merged (target Entity). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- A JSON-LD document representing an NGSI-LD Entity Fragment. -- An optional flag indicating whether the JSON-LD document contains a simplified representation of the entity. -- An optional parameter indicating a common *observedAt* timestamp to use across merged Attributes. -- An optional parameter representing a common IETF RFC 5646 [[28]](7-tabreferences.md#28) language tag to use across merged LanguageMap Attributes. -::: - -#### 5.6.17.4 Behaviour {#tabbehaviour-16 number="10.6.17.4"} - -The following behaviour shall be exhibited by compliant implementations: - -::: B1plus -- If the Entity ID is not present or it is not a valid URI then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), then an error of type *ResourceNotFound* shall be raised. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, Attributes from matching input data are forwarded. For each matching registration: -::: - -::: B2plus -- If the Merge Entity operation is supported by the matched registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Merge Entity operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete Merge Entity operation failed, or in a partial success if some parts of it succeeded. -::: - -::: B1 -The matching Attributes are then removed from the Fragment and not processed further. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded in the case the Merge Entity operation is supported for remote processing to matching endpoints. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type *OperationNotSupported* shall be raised. -::: - -::: B1 -Then, implementations shall perform a merge operation over the target Entity as mandated by [clause 5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour), using the following procedure: -::: - -::: B1 -For each Attribute (Property or Relationship) included by the Entity Fragment: -::: - -::: B2plus -- If the target Entity does not include a matching Attribute (considering term expansion rules as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)), then such Attribute shall be appended to the target Entity. -- If the target Entity already includes a matching Attribute (considering term expansion rules as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)): -::: - -::: B3plus -- If the Attribute (Property or Relationship) to be merged is represented in a simplified representation, the *type* of any pre-existing Attribute in the target entity shall be preserved. -- If a common language tag is defined and a *LanguageProperty* Attribute to be merged is represented as a string, the pre-existing *languageMap* JSON object shall be preserved. The string value shall only replace the value associated to the language tag key found within the *languageMap*. -- If a common *observedAt* timestamp is defined and an existing Attribute to be merged previously contained an *observedAt* sub-Attribute, the *observedAt* sub-Attribute is also updated using the common timestamp, unless the Entity Fragment itself contains an explicit updated value for the *observedAt* sub-Attribute. -- If a *datasetId* is present in the Attribute included by the Entity Fragment: -::: - -::: B4 -- If an Attribute instance in the target Entity has the same*datasetId* -- If overwrite is allowed and the Attribute value is not NGSI-LD Null, then the existing Attribute with the specified*datasetId* -- If overwrite is allowed and the Attribute value is NGSI-LD Null, then the existing Attribute with the specified*datasetId* -- If overwrite is not allowed, the existing Attribute with the specified*datasetId* -- Otherwise the Attribute instance with the specified*datasetId* -::: - -::: B3plus -- If no *datasetId* is present in the Attribute included by the Entity Fragment, the default Attribute instance is targeted: -::: - -::: B4 -- If the default Attribute instance is present: -- If overwrite is allowed and the Attribute value is not NGSI-LD Null, then the existing Attribute in the target Entity shall be merged with the new one supplied. -- If overwrite is allowed and the Attribute value is NGSI-LD Null, then the existing Attribute with the specified*datasetId* -- If overwrite is not allowed, the existing Attribute in the target Entity shall be left untouched. -- Otherwise if value is not NGSI-LD Null, the default Attribute instance shall be appended to the target Entity. -::: - -::: B1plus -- If *type* is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity. -- If *scope* is included in the Fragment and overwrite is allowed, the scope of the target Entity will become the one included in the Fragment. Otherwise, the Scopes in the Fragment that are not part of the value of *scope* of the target Entity will be appended to the value of the *scope* of the target Entity. If there is more than one Scope, the value of *scope* is represented as a JSON array containing all Scopes. -::: - -#### 5.6.17.5 Output data {#taboutput-data-16 number="10.6.17.5"} - -::: B1plus -- A status code indicating whether all the Attributes were merged successfully. -- List of Attributes (Properties and/or Relationships) actually merged. -::: - -### 5.6.18 Replace Entity {#tabreplace-entity number="10.6.18"} - -#### 5.6.18.1 Description {#tabdescription-17 number="10.6.18.1"} - -This operation allows the modification of an existing NGSI-LD Entity by replacing all of the Attributes (Properties or Relationships). - -#### 5.6.18.2 Use case diagram {#tabuse-case-diagram-17 number="10.6.18.2"} - -A [Context Producer]{.HTML_Keyboard} can replace an entire Entity within an NGSI-LD system as shown in [Figure 5.6.18.2‑1](10-tabapi-operation-definition.md#Figure_5.6.18.2-1). - -::: FL -![](./media/image33.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.18.2-1 .TF} -Figure 5.6.18.2-1: Replace Entity use case -::: - -#### 5.6.18.3 Input data {#tabinput-data-17 number="10.6.18.3"} - -::: B1plus -- A URI representing the id of the Entity to be replaced (target Entity). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- A JSON-LD document representing an NGSI-LD Entity. -::: - -#### 5.6.18.4 Behaviour {#tabbehaviour-17 number="10.6.18.4"} - -::: B1plus -- If the target Entity ID is not a valid URI or it is not present, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), then an error of type *ResourceNotFound* shall be raised. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. NGSI-LD Nulls are not supported by this operation. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, Attributes from matching input data are forwarded. For each matching registration: -::: - -::: B2plus -- If the Replace Entity operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Replace Entity operation is not supported by the registration, this shall result in an error of type *Conflict* in case the complete Replace Entity operation failed, or in a partial success if some parts of it succeeded. -::: - -::: B1plus -- The matching Attributes are then removed from the Fragment and not processed further. -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded in the case the Replace Entity operation is supported for remote processing to matching endpoints. -- If the target Entity exists locally, completely replace the existing Entity with the same Entity ID with the new Entity content provided. The system generated *createdAt* Temporal Property of the Entity as defined in [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) remain unchanged. -::: - -#### 5.6.18.5 Output data {#taboutput-data-17 number="10.6.18.5"} - -None. - -### 5.6.19 Replace Attribute {#tabreplace-attribute number="10.6.19"} - -#### 5.6.19.1 Description {#tabdescription-18 number="10.6.19.1"} - -This operation allows the replacement of a single Attribute (Property or Relationship) within an NGSI-LD Entity. - -#### 5.6.19.2 Use case diagram {#tabuse-case-diagram-18 number="10.6.19.2"} - -A [Context Producer]{.HTML_Keyboard} can carry out a replacement of an Attribute within an Entity within an NGSI-LD System as shown in [Figure 5.6.19.2‑1](10-tabapi-operation-definition.md#Figure_5.6.19.2-1). - -::: FL -![](./media/image34.png){style="width:3.45833in;height:2.94444in"} -::: - -::: {#Figure_5.6.19.2-1 .TF} -Figure 5.6.19.2-1: Replace Attribute use case -::: - -#### 5.6.19.3 Input data {#tabinput-data-18 number="10.6.19.3"} - -::: B1plus -- Entity ID (URI) of the concerned Entity, the target Entity. -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- Target Attribute (Property or Relationship) to be replaced, identified by a name. -- A JSON-LD document representing an NGSI-LD Attribute Fragment. -::: - -#### 5.6.19.4 Behaviour {#tabbehaviour-18 number="10.6.19.4"} - -::: B1plus -- If the target Entity ID is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the target Attribute name is not valid, then an error of type *BadRequestData* shall be raised. -- If the target Attribute is *scope*, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations)), then an error of type *ResourceNotFound* shall be raised. -- The behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the input data, the input data is forwarded. For each matching registration: -::: - -::: B2plus -- If the Replace Attribute operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Replace Attribute operation is not supported by the registration, this shall result in an error of type *Conflict* in case the complete Replace Attribute operation failed, or in a partial success if some parts of it succeeded. -::: - -::: B1 -No further processing is required. -::: - -::: B1plus -- For any **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the remaining input data, that input data is also forwarded in the case the Replace Attribute operation is supported for remote processing to matching endpoints. -- Apply term expansion as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction), so that the fully qualified name (URI) associated to the target Attribute is properly obtained. -- If the target Entity does not contain the target Attribute: -::: - -::: B2plus -- as a default instance in case no *datasetId* is present; -- as an instance with the specified *datasetId* if present; -- then this shall result in an error of type *ResourceNotFound* in case the complete Replace Attribute operation failed, or in a partial success if some parts of it succeeded. -::: - -::: B1plus -- Completely replace the existing Attribute instance with the new Attribute content provided. The system generated *createdAt* Temporal Property as defined in [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) remains unchanged. -::: - -#### 5.6.19.5 Output data {#taboutput-data-18 number="10.6.19.5"} - -None. - -### 5.6.20 Batch Entity Merge {#tabbatch-entity-merge number="10.6.20"} - -#### 5.6.20.1 Description {#tabdescription-19 number="10.6.20.1"} - -This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch processing rules defined in IETF RFC 7396 [[16]](7-tabreferences.md#16) by adding new attributes (Properties or Relationships) or modifying or deleting existing attributes associated with an existing Entity. - -#### 5.6.20.2 Use case diagram {#tabuse-case-diagram-19 number="10.6.20.2"} - -A [Context Producer]{.HTML_Keyboard} can merge a batch of Entities within an NGSI-LD system as shown in [Figure 5.6.20.2‑1](10-tabapi-operation-definition.md#Figure_5.6.20.2-1). - -::: FL -![](./media/image35.png){style="width:3.47222in;height:3.08333in"} -::: - -::: {#Figure_5.6.20.2-1 .TF} -Figure 5.6.20.2-1: Merge a batch of Entities use case -::: - -#### 5.6.20.3 Input data {#tabinput-data-19 number="10.6.20.3"} - -A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity). See [clause 5.5.11.5](10-tabapi-operation-definition.md#tabbatch-entity-merge-case) for information on behaviour when there is more than one instance of the same entity in the input Array. - -#### 5.6.20.4 Behaviour {#tabbehaviour-19 number="10.6.20.4"} - -Implementations shall exhibit the following behaviour: - -::: B1plus -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized as the empty array. -- Let E be an array which shall contain a list of *BatchEntityError* as defined by [clause 5.2.17](10-tabapi-operation-definition.md#tabbatchentityerror), one for each NGSI-LD Entity which resulted in error. E shall be initialized as the empty array. -- For each [Context Source Registration]{.HTML_Keyboard} CSR in the [Context Registry]{.HTML_Keyboard}: -::: - -::: B2plus -- Let IN be a copy of the original input array. -- Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **exclusive** [Context Source Registration]{.HTML_Keyboard}, which is not CSR itself. -- Remove all Attributes from the remaining Entities in IN for which there is a matching **redirect** [Context Source Registration]{.HTML_Keyboard}, unless CSR is a redirect [Context Source Registration]{.HTML_Keyboard} itself. -- Remove all Entities without Attributes from IN. -- If IN is empty, continue with the next [Context Source Registration]{.HTML_Keyboard} if there is any. -- If the Batch Entity Merge operation is supported by CSR: -::: - -::: B3plus -- Forward the Batch Entity Merge request with IN as input Array. -- Merge the returned list of Entities successfully created with S. -- Merge the returned list of Entities in Error with E. -::: - -::: B2plus -- Otherwise, if the Merge Entity operation [(clause 5.6.17](10-tabapi-operation-definition.md#tabmerge-entity)) is supported by CSR: -::: - -::: B3plus -- For each Entity EN in the input array: -::: - -::: B4 -- Forward a Merge Entity request for Entity EN. -- Merge any successful result(s) for Entity EN merged with S. -- Merge any error result(s) for Entity EN merged with E. -::: - -::: B2plus -- Otherwise: -::: - -::: B3plus -- In case CSR is an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard}, add an Error of type *Conflict* for each Entity in IN to E. -::: - -::: B1plus -- For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by [clause 5.6.17](10-tabapi-operation-definition.md#tabmerge-entity), but limited to a local operation, as follows: -::: - -::: B2plus -- If the Entity was successfully merged (Attributes updated, appended or deleted), then add the corresponding Entity ID to the S array. -- If the Entity merge failed, then a new *BatchEntityError* shall be added to E containing the failed Entity ID and the *ProblemDetails* associated. -::: - -#### 5.6.20.5 Output data {#taboutput-data-19 number="10.6.20.5"} - -::: B1plus -- none (if all Entities already existed and are successfully merged); or -- the list of Entities successfully merged (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully merged. -::: - -### 5.6.21 Purge Entities {#tabpurge-entities number="10.6.21"} - -#### 5.6.21.1 Description {#tabdescription-20 number="10.6.21.1"} - -This operation allows the deletion of entities within an NGSI-LD system based upon a query. - -#### 5.6.21.2 Use case diagram {#tabuse-case-diagram-20 number="10.6.21.2"} - -A [Context Producer]{.HTML_Keyboard} can delete a set of entities which matches a specific query from an NGSI-LD system as shown in [Figure 5.6.21.2‑1](10-tabapi-operation-definition.md#Figure_5.6.21.2-1). - -::: FL -![](./media/image36.png){style="width:3.48611in;height:2.72222in"} -::: - -::: {#Figure_5.6.21.2-1 .TF} -Figure 5.6.21.2-1: Purge Entities use case -::: - -#### 5.6.21.3 Input data {#tabinput-data-20 number="10.6.21.3"} - -::: B1plus -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector. -- A list (one or more) of Entity identifiers (optional). -- A restrictive list of Attribute names to be deleted as attributes (optional). -- An exclusionary list Attribute names to be kept as attributes (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- An NGSI-LD query (called context source filter, to filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -::: - -In the general case, it is not possible to purge a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. - -#### 5.6.21.4 Behaviour {#tabbehaviour-20 number="10.6.21.4"} - -::: B1plus -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names, including at least one non-system Attribute; -::: - -::: B2 -c) NGSI-LD Query, including at least one non-system Attribute; -::: - -::: B2 -d) NGSI-LD GeoQuery; -::: - -::: B2 -e) local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). -::: - -::: B1 -If none of the above is provided, then an error of type *BadRequestData* shall be raised (too wide query). -::: - -::: B1plus -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) an error of type *BadRequestData* shall be raised. -- If projection attributes are present and indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, then an error of type *BadRequestData* shall be raised. -- If the filter conditions specified by the query includes [Linked Entity]{.HTML_Keyboard} attributes then an error of type *BadRequestData* shall be raised. -- Term to URI expansion of type and Attribute names shall be performed, as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- Otherwise, implementations shall run a Query Entities operation [(clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes)) to retrieve a list of ids of Entities for deletion, that meet all of the following conditions (given the respective parameter is provided): -::: - -::: B2plus -- id is equal to any of the id(s) passed as a parameter; -- the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter; -- Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter; -- id matches the id pattern passed as a parameter; -- the filter conditions specified by the query are met (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); -- the geospatial restrictions imposed by the geoquery are met (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); if there are multiple instances of the *GeoProperty* on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions; -- if the Scope query is present, it shall match a present Entity Scope (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.15](15-annex-c-informative-examples-of-using-the-api.md#c.5.15tabscope-queries)). -::: - -::: B1 -And thereafter: -::: - -::: B2plus -- when no restrictive list of Entity member names is present, the implementation shall delete all Entities that can be found locally using retrieved list of Entity ids; -- when a restrictive list of Entity member names is present, the implementation shall delete the given set of Attributes with those member names from all Entities that can be found locally using retrieved list of Entity ids; -- when an exclusionary list of Entity member names is present, the implementation shall delete all but the given set of Attributes with those member names from all Entities that can be found locally using retrieved list of Entity ids. -::: - -::: B1plus -- Unless local scope is specified (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), for [Context Source Registrations]{.HTML_Keyboard} that match the query and support the "purgeEntity" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -- If an **inclusive,** **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} matches against the filter conditions specified, the request is forwarded for remote processing. For each matching registration: -::: - -::: B2plus -- If the Purge Entity operation is supported by the registration (see [clause 4.3.6](9-tabcontext-information-management-framework.md#tabdistributed-operations)), matching input data is forwarded to the Registration endpoint. -- If the Purge Entity operation is not supported by the matched registration, this shall result in an error of type *Conflict* in case the complete purge Entities failed, or in a partial success if some parts of purge Entities succeeded. -::: - -#### 5.6.21.5 Output data {#taboutput-data-20 number="10.6.21.5"} - -None. - -## 5.7 Context Information Consumption {#tabcontext-information-consumption number="10.7"} - -### 5.7.1 Retrieve Entity {#tabretrieve-entity number="10.7.1"} - -#### 5.7.1.1 Description {#tabdescription-21 number="10.7.1.1"} - -This operation allows retrieving an NGSI-LD Entity. - -#### 5.7.1.2 Use case diagram {#tabuse-case-diagram-21 number="10.7.1.2"} - -A *Context Consumer* can retrieve a specific Entity from an NGSI-LD system as shown in [Figure 5.7.1.2‑1](10-tabapi-operation-definition.md#Figure_5.7.1.2-1). - -::: FL -![](./media/image37.png){style="width:3.48611in;height:3.90278in"} -::: - -::: {#Figure_5.7.1.2-1 .TF} -Figure 5.7.1.2-1: Retrieve Entity use case -::: - -#### 5.7.1.3 Input data {#tabinput-data-21 number="10.7.1.3"} - -::: B1plus -- Entity ID (URI) of the Entity to be retrieved (target Entity). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). -- List of Attribute (*Properties* or *Relationships*) names to be retrieved (projection attributes) (optional). -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- A language filter as defined by [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -- An optional JSON-LD context. -- In the case of a GeoJSON representation, the name of the *GeoProperty* attribute to use as the geometry for the GeoJSON representation as mandated by [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) (optional). -- An optional flag indicating whether to include additional [Linked Entities]{.HTML_Keyboard} corresponding to the *Relationships* retrieved and how to format those [Linked Entities]{.HTML_Keyboard}[.]{.HTML_Definition} See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A limit to the depth of [Linked Entities]{.HTML_Keyboard} to search whilst traversing an Entity graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A list (one or more) of [Linked Entity identifier]{.HTML_Keyboard}s previously encountered whilst traversing an Entity graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A flag indicating whether to return the location of the EntityMap used within the operation (optional). -- A suggested lifetime for the EntityMap, if EntityMap is to be created (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (optional). -- A [datasetId ]{.HTML_Variable}parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -::: - -#### 5.7.1.4 Behaviour {#tabbehaviour-21 number="10.7.1.4"} - -::: B1plus -- If the Entity ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If geometryProperty parameter is present and the Accept Header is not set to ["application/geo+json"]{.HTML_Code}, then an error of type *BadRequestData* shall be raised. -- If projection attributes are present and indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval and the use of [Linked Entity ]{.HTML_Keyboard}retrieval is not specified, or the projected attribute depth exceeds the [Linked Entity ]{.HTML_Keyboard}retrieval depth, an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity held locally whose id (URI), and where specified type, is equivalent, and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- The implementation shall retrieve any Attribute data held locally which is associated with the Entity defined by the Entity ID. -- If the ContextBroker implementation supports the use of EntityMaps then: -::: - -::: B2plus -- If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved: -::: - -::: B3plus -- If the resource cannot be found, or the data has expired, a new EntityMap shall be created. -- If the data has not expired, **only** the retrieved Entity Map shall be used to determine which [Context Source Registrations]{.HTML_Keyboard} match the Entity ID. -::: - -::: B2plus -- If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created. -::: - -::: B1plus -- For [Context Source Registrations]{.HTML_Keyboard} that match and support the retrieveEntity operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If an EntityMap is in use for this operation, and an EntityMap entry linked to a [Context Source Registration]{.HTML_Keyboard} is found, the location of the linked EntityMap shall be passed as part of any forwarded request. -- For any **exclusive**, **redirect** and **inclusive** [Context Source Registrations]{.HTML_Keyboard}, the request is forwarded for remote retrieval by matching endpoints, and remote Attribute data for the Entity is received. If an *expiresAt DateTime* is present on the Entity and the date lies in the past, the Attribute data shall be discarded, otherwise the Attribute data is then merged together according to the algorithm defined in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- For any **auxiliary** [Context Source Registrations]{.HTML_Keyboard} the remote Attribute data received is added to the payload only when an Attribute is not present in any of the Attribute data received elsewhere. -- If an EntityMap is in use for this operation, the EntityMap's linked maps are updated to hold the location of every EntityMap used by the [Context Source Registrations.]{.HTML_Keyboard} -::: - -::: B1plus -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- For each Attribute found in the target Entity, when the [datasetId ]{.HTML_Variable}parameter is provided in the request: -::: - -::: B2plus -- Filter the Attribute instances based on the [datasetId ]{.HTML_Variable}parameter, i.e. keep only the Attribute instances whose [datasetId]{.HTML_Variable} is specified. The default Attribute instance is matched, if ["@none"]{.HTML_Code} is specified. -- If there is no Attribute instance whose [datasetId ]{.HTML_Variable}matches the value of the parameter, the Attribute shall not be returned with the Entity. -::: - -::: B1plus -- If the optional Attribute list is present and the NGSI-LD endpoint does know about a matching Entity for the Entity ID, but this Entity does not have any of the Attributes in the Attribute list, then an error of type *ResourceNotFound* shall be raised. -- If the Accept Header is set to ["application/json"]{.HTML_Code} or ["application/ld+json"]{.HTML_Code}, return a JSON-LD object representing the Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) and containing only the Attributes requested (if present). -::: - -::: B2plus -- If the Prefer Header [[26]](7-tabreferences.md#26) is set to "ngsi-ld=" then the ContextBroker shall endeavour to amend the JSON-LD object to conform to the specified version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads), and return a Preference-Applied Header set to "ngsi-ld=" in the response. -::: - -::: B1plus -- If the Accept Header is set to ["application/geo+json"]{.HTML_Code}, a GeoJSON *Feature* object representing the entity as mandated by [clause 5.2.29](10-tabapi-operation-definition.md#tabfeature) and containing only the Attributes requested (if present): -::: - -::: B2plus -- If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML_Code} then the *Feature* object will also contain an *\@context* field. -- If the Prefer Header is set to ["body=json"]{.HTML_Code} the *\@context* is set as a Link Header and removed from the Feature object. -::: - -#### 5.7.1.5 Output data {#taboutput-data-21 number="10.7.1.5"} - -A JSON-LD object representing the target Entity as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) or a GeoJSON *Feature* as mandated by [clause 5.2.29](10-tabapi-operation-definition.md#tabfeature). - -If a restrictive list of Entity member names is present, the Entity is reduced down to only contain the defined Entity members (applies to all Entities in the payload in the case of [Linked Entity]{.HTML_Keyboard} retrieval). - -If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from the Entity (applies to all Entities in the payload in the case of [Linked Entity]{.HTML_Keyboard} retrieval). - -If any of the returned Attributes corresponds to a [VocabProperty]{.HTML_Keyboard}, the returned value shall be compacted according to the supplied *\@context*. - -If a language filter is specified and any of the returned Attributes corresponds to a *LanguageProperty*, the *LanguageProperty* in question shall be converted into a *Property*. The value of this *Property* shall correspond to the value of the string or strings from the matching key-value pair of the *languageMap* where the key matches the language filter. A non-reified subproperty *lang* shall be included in the response indicating the chosen language. - -If no match can be made for a *LanguageProperty* then a single language shall be chosen, up to the implementation. - -If **inline** [Linked Entity]{.HTML_Keyboard} **retrieval** (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) is specified, and any of the returned Attributes corresponds to an annotated *Relationship*, then unless a URI has been previously encountered, an *entity* sub-Property shall be included in the response holding the [Linked Entity]{.HTML_Keyboard} data for each URI corresponding to that *Relationship's* target *object* URI. If any of the returned Attributes corresponds to an annotated *ListRelationship*, then an *entityList* subproperty shall be included in the response holding the **ordered** array of [Linked Entities]{.HTML_Keyboard} corresponding to that *ListRelationship's* target *objectList* URIs unless a URI has been previously encountered. - -If **flattened** [Linked Entity]{.HTML_Keyboard} **retrieval** (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)) is specified, the response shall be an array of JSON-LD objects representing the target entity itself and the targets of its *Relationships*. If any of the returned Attributes corresponds to an annotated *Relationship*, unless a target URI has been previously encountered, thedata corresponding to each URI of the Relationship's target *object* URIs is appended to the array. If any of the returned Attributes corresponds to an annotated *ListRelationship*, then an **ordered** array of additional [Linked Entities]{.HTML_Keyboard} is appended to the array which hold the data corresponding to each of the URIs found within *ListRelationship's* target *objectList* unless a URI has been previously encountered. - -::: ondemand_PAR_space_after_10 -Flattened [Linked Entity]{.HTML_Keyboard} retrieval output changes to a GeoJSON *FeatureCollection* as mandated by [clause 5.2.30](10-tabapi-operation-definition.md#tabfeaturecollection) if the Accept Header is set to ["application/geo+json"]{.HTML_Code}. -::: - -If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response. - -### 5.7.2 Query Entities {#tabquery-entities number="10.7.2"} - -#### 5.7.2.1 Description {#tabdescription-22 number="10.7.2.1"} - -This operation allows querying an NGSI-LD system. - -#### 5.7.2.2 Use case diagram {#tabuse-case-diagram-22 number="10.7.2.2"} - -A *Context Consumer* can retrieve a set of entities which matches a specific query from an NGSI-LD system as shown in [Figure 5.7.2.2‑1](10-tabapi-operation-definition.md#Figure_5.7.2.2-1). - -::: FL -![](./media/image38.png){style="width:3.48611in;height:3.90278in"} -::: - -::: {#Figure_5.7.2.2-1 .TF} -Figure 5.7.2.2-1: Query Entities use case -::: - -#### 5.7.2.3 Input data {#tabinput-data-22 number="10.7.2.3"} - -::: B1plus -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector. -- A list (one or more) of Entity identifiers (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional, deprecated). -- An NGSI-LD query (called context source filter, to filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- A limit to the number of Entities to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -- A specified language filter as per [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -- A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional). -- An optional flag indicating whether to include additional [Linked Entities]{.HTML_Keyboard} corresponding to the *Relationships* retrieved and how to format those [Linked Entities]{.HTML_Keyboard}*.* See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A limit to the depth of [Linked Entities]{.HTML_Keyboard} to search whilst traversing an Entity Graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A list (one or more) of [Linked Entity identifier]{.HTML_Keyboard}s previously encountered whilst traversing an Entity Graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A flag indicating whether to return the location of the EntityMap used within the operation (optional). -- A suggested lifetime for the EntityMap, if EntityMap is to be created (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (optional). -- A *datasetId* parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -- A list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be used to define the preferred ordering of Entities retrieved (Entity ordering attributes as defined by [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering)) (optional). -- A preferred collation setting to be used when applying ordering of Entities (optional). -- A location to be used when applying ordering of Entities (optional). -- A defined geometry type to be used when applying ordering of Entities (optional). -- A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional). -- In the case of GeoJSON representation, the name of the *GeoProperty* attribute to use as the geometry for the GeoJSON representation as mandated by [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) (optional). -::: - -In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. - -#### 5.7.2.4 Behaviour {#tabbehaviour-22 number="10.7.2.4"} - -::: B1plus -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names, including at least one non-system Attribute; -::: - -::: B2 -c) NGSI-LD Query, including at least one non-system Attribute; -::: - -::: B2 -d) NGSI-LD GeoQuery; -::: - -::: B2 -e) local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). -::: - -::: B1 -If none of the above is provided, then an error of type *BadRequestData* shall be raised (too wide query). -::: - -::: B1plus -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) an error of type *BadRequestData* shall be raised. -- If projection attributes are present and indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, and the use of [Linked Entity ]{.HTML_Keyboard}retrieval is not specified, or the projected attribute depth exceeds the [Linked Entity ]{.HTML_Keyboard}retrieval depth, then an error of type *BadRequestData* shall be raised. -- If the filter conditions specified by the query includes [Linked Entity]{.HTML_Keyboard} attributes, and the use of [Linked Entity ]{.HTML_Keyboard}retrieval is not specified, or the [Linked Entity ]{.HTML_Keyboard}attribute query depth exceeds the [Linked Entity ]{.HTML_Keyboard}retrieval depth, an error of type *BadRequestData* shall be raised (too deep query). -- If geometryProperty parameter is present and the Accept Header is not set to ["application/geo+json",]{.HTML_Code} then an error of type *BadRequestData* shall be raised. -- If the ordering parameter is present and the execution of the operation is not limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)) then an error of type *BadRequestData* shall be raised. -- If the ordering parameter is present and refers to ordering by distance and no location is present, then an error of type *BadRequestData* shall be raised. -- If a preferred collation setting is present and it does not conform to a valid ICU collation (see IETF RFC 6067 [[36]](7-tabreferences.md#36)) then an error of type *BadRequestData* shall be raised. -- If a location to be used when applying ordering of Entities setting is present and it is not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) or an error of type *BadRequestData* shall be raised. -- Otherwise, -::: - -::: B2plus -- Term to URI expansion of type and Attribute names shall be performed, as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -::: - -::: B1plus -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided): -::: - -::: B2plus -- id is equal to any of the id(s) passed as a parameter; -- the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter; -- id matches the id pattern passed as a parameter. -::: - -::: B1plus -- otherwise, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet **all** of the following conditions (given the respective parameter is provided): -::: - -::: B2plus -- id is equal to any of the id(s) passed as a parameter; -- the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter; -- Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter; -- id matches the id pattern passed as a parameter; -- the filter conditions specified by the query are met (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); -- the geospatial restrictions imposed by the geoquery are met (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); if there are multiple instances of the *GeoProperty* on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions; -- if the Scope query is present, it shall match a present Entity Scope (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.15](15-annex-c-informative-examples-of-using-the-api.md#c.5.15tabscope-queries)); -- if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list. -::: - -::: B1plus -- If the ContextBroker implementation supports the use of EntityMaps then: -::: - -::: B2plus -- If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved: -::: - -::: B3plus -- If the resource cannot be found, or the data has expired, a new EntityMap shall be created. -- If the data has not expired, **only** the retrieved EntityMap shall be used to determine which [Context Source Registrations]{.HTML_Keyboard} match the Entity ID. -::: - -::: B2plus -- If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created. -::: - -::: B1plus -- Unless local scope is specified (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), for [Context Source Registrations]{.HTML_Keyboard} that match the query and support the "queryEntity" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If an EntityMap is in use for this operation, and an EntityMap entry linked to a [Context Source Registration]{.HTML_Keyboard} is found, the location of the EntityMap shall be passed as part of the forwarded request. -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. These filters then have to be applied after the Entity information from different Context Sources and local information, if there is any, has been aggregated. -- For any **exclusive**, **redirect** and **inclusive** [Context Source Registrations]{.HTML_Keyboard}, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an Entity Array. Within each Entity Array, any Entities where an *expiresAt DateTime* is present and the date lies in the past shall be discarded. The Entity Arrays are then merged together with the locally queried result according to the algorithm defined in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- For any **auxiliary** [Context Source Registrations]{.HTML_Keyboard}, the request is forwarded for remote querying by matching endpoints. Data from the Entity Array received is added to the payload only when an Attribute is not already present in the merged Entity Arrays are received elsewhere. -::: - -::: B1plus -- If split Entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split Entities, and local scope is not specified, the following filters shall be applied on the aggregated Entities: -::: - -::: B2plus -- the filter conditions specified by the query are met (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); -- the geospatial restrictions imposed by the geoquery are met (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); if there are multiple instances of the *GeoProperty* on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions; -- if the Scope query is present, it shall match a present Entity Scope (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.15](15-annex-c-informative-examples-of-using-the-api.md#c.5.15tabscope-queries)); -- if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list. -::: - -- ::: B1plus - Pagination logic shall be in place as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). - ::: - -- If in the process of obtaining the query result it is necessary to issue a [Context Source]{.HTML_Keyboard} discovery operation, the same [Context Source]{.HTML_Keyboard} filter input parameter (if present) shall be propagated. - -- ::: B1plus - For each Attribute found in the target Entity, when [datasetId ]{.HTML_Variable}parameter is provided in the request: - ::: - -::: B2plus -- Filter the Attribute instances based on the [datasetId ]{.HTML_Variable}parameter, i.e. keep only the Attribute instances whose [datasetId]{.HTML_Variable} is specified. The default Attribute instance is matched, if ["@none"]{.HTML_Code} is specified. -- If there is no Attribute instance whose [datasetId ]{.HTML_Variable}matches the value of the parameter, the Attribute shall not be returned with the Entity. -::: - -::: B1plus -- If the Accept Header is set to ["application/json"]{.HTML_Code} or ["application/ld+json",]{.HTML_Code} a JSON-LD array is returned, representing the Entities as mandated by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) and containing only the Attributes requested (if present). -::: - -::: B2plus -- If the Prefer Header [[26]](7-tabreferences.md#26) is set to "ngsi-ld=" then the ContextBroker shall endeavour to amend the elements of the JSON-LD array to conform to the specified version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads), and return a Preference-Applied Header set to "ngsi-ld=" in the response. -::: - -::: B1plus -- If the Accept Header is set to ["application/geo+json",]{.HTML_Code} the response shall be a GeoJSON *FeatureCollection* as mandated by [clause 5.2.30](10-tabapi-operation-definition.md#tabfeaturecollection), with each *Feature* within the *FeatureCollection* containing only the Attributes requested (if present): -::: - -::: B2plus -- If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML_Code} then the *FeatureCollection* will also contain an \@context field. -- If the Prefer Header is set to ["body=json]{.HTML_Code}*"* the *\@context* is sent as a Link Header and removed from the *FeatureCollection* object. -::: - -#### 5.7.2.5 Output data {#taboutput-data-22 number="10.7.2.5"} - -::: ondemand_PAR_space_after_10 -A JSON-LD array representing the matching entities as defined by [clause 5.2.4](10-tabapi-operation-definition.md#tabentity) or in the case of GeoJSON requests a *FeatureCollection* as mandated by [clause 5.2.30](10-tabapi-operation-definition.md#tabfeaturecollection). If Entity ordering is specified (see [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering)), then the JSON-LD array or *FeatureCollection* returned shall be ordered according to the list of member names specified. For each matching Entity, only the Attributes specified by the Attribute list parameter shall be included. If such parameter is not present, then all Attributes shall be included. -::: - -If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members. - -If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload. - -If any of the returned Attributes corresponds to a [VocabProperty]{.HTML_Keyboard}, the returned value shall be compacted according to the supplied *\@context*. - -If a language filter is specified and any of the returned Attributes corresponds to a *LanguageProperty*, the *LanguageProperty* in question shall be converted into a *Property*. The value of this *Property* shall correspond to the value of the string or strings from matching key-value pair of the *languageMap* where the key matches the language filter. A non-reified subproperty *lang*shall be included in the response indicating the chosen language. - -If no match can be made for a *LanguageProperty*, then the default identified by the JSON-LD ["@none]{.HTML_Code}["]{.HTML_Code} shall be chosen if present, otherwise the choice of a single language is up to the implementation. - -If **inline** [Linked Entity]{.HTML_Keyboard} **retrieval** (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) is specified, and any of the returned Attributes corresponds to an annotated *Relationship*, then unless a URI has been previously encountered, an *entity* subproperty shall also be included in the response holding the data for each URI corresponding to that *Relationship's* target *object* URIs. If any of the returned Attributes corresponds to an annotated *ListRelationship*, then an *entityList* subproperty shall also be included in the response holding the **ordered** data corresponding to that *ListRelationship's* target *objectList* URIs, unless a URI has been previously encountered. - -If **flattened** [Linked Entity]{.HTML_Keyboard} **retrieval** (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)) is specified, the response shall be an array of JSON-LD objects representing the matching entities and the targets of their *Relationships*. If any of the returned Attributes corresponds to an annotated *Relationship*, unless a URI has been previously encountered, then data for each URI corresponding to the *Relationship's* target *object* URIs is appended to the array. If any of the returned Attributes corresponds to an annotated *ListRelationship*, then an array of additional [Linked Entities]{.HTML_Keyboard} is appended to the array which hold the data corresponding to each of the URIs found within *ListRelationship's* target *objectList* unless a URI has been previously encountered. - -If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response. - -### 5.7.3 Retrieve Temporal Evolution of an Entity {#tabretrieve-temporal-evolution-of-an-entity number="10.7.3"} - -#### 5.7.3.1 Description {#tabdescription-23 number="10.7.3.1"} - -This operation allows retrieving the [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of an Entity]{.HTML_Keyboard}. - -#### 5.7.3.2 Use case diagram {#tabuse-case-diagram-23 number="10.7.3.2"} - -A [Context Consumer]{.HTML_Keyboard} can retrieve the [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of an Entity]{.HTML_Keyboard} (in the form of a temporal representation) from an NGSI-LD system as shown in [Figure 5.7.3.2‑1](10-tabapi-operation-definition.md#Figure_5.7.3.2-1). - -::: FL -![](./media/image39.png){style="width:3.47222in;height:3.05556in"} -::: - -::: {#Figure_5.7.3.2-1 .TF} -Figure 5.7.3.2-1: Retrieve Temporal Evolution of an Entity use case -::: - -#### 5.7.3.3 Input data {#tabinput-data-23 number="10.7.3.3"} - -::: B1plus -- Entity ID (URI) of the target [Temporal Evolutionof an Entity]{.HTML_Keyboard} to be retrieved. -- List of Attribute (Properties or Relationships) names to be retrieved (projection attributes) (optional). -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An NGSI-LD temporal query as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language) (optional). -- A parameter (*lastN*) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional). -- An optional JSON-LD context. -- A flag indicating whether to return the location of the EntityMap used within the operation (optional). -- A suggested lifetime for the EntityMap, if EntityMap is to be created (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (optional). -- A [datasetId ]{.HTML_Variable}parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -::: - -#### 5.7.3.4 Behaviour {#tabbehaviour-23 number="10.7.3.4"} - -::: B1plus -- If the Entity ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If projection attributes are present and indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally, and no matching registrations apply, then an error of type *ResourceNotFound* shall be raised. -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- The *lastN* parameter refers to a number, *n*, of Attribute instances which shall correspond to the last *n* timestamps (in descending ordering) of the temporal property (by default *observedAt*) within the concerned temporal interval. -- Let S be the [Temporal Evolution of theEntity]{.HTML_Keyboard} as mandated by [clause 5.2.20](10-tabapi-operation-definition.md#tabentitytemporal) with the specified Entity ID as it is available locally. S is empty in case no [Temporal Evolution of the Entity]{.HTML_Keyboard} is available locally. -- From S, select only those Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset. -- If the ContextBroker implementation supports the use of EntityMaps then: -::: - -::: B2plus -- If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved: -::: - -::: B3plus -- If the resource cannot be found, or the data has expired, a new EntityMap shall be created. -- If the data has not expired, **only** the retrieved Entity Map shall be used to determine which [Context Source Registrations]{.HTML_Keyboard} match the Entity ID. -::: - -::: B2plus -- If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created. -::: - -::: B1plus -- For [Context Source Registrations]{.HTML_Keyboard} that match the Entity ID and support the "retrieveTemporal" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If an EntityMap is in use for this operation, and an EntityMap entry linked to a [Context Source Registration]{.HTML_Keyboard} is found, the location of the linked EntityMap shall be passed as part of any forwarded request. -- For any **exclusive**, **redirect** and **inclusive** [Context Source]{.HTML_Keyboard}, the request is forwarded for remote retrieval by matching endpoints. and remote Attribute data for the Entity is received. The result is then merged together with S1 according to the algorithm defined in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- For any **auxiliary** [Context Source Registrations]{.HTML_Keyboard} the remote Attribute data received is added to S1 only when the Attribute instance, whose value of the *timeproperty*, which is used for the temporal query (*observedAt* as default), is not present in any of the Attribute instances received from elsewhere. -- If an EntityMap is in use for this operation, the EntityMap's linked maps are updated to hold the location of every EntityMap used by the [Context Source Registrations.]{.HTML_Keyboard} -::: - -::: B1plus -- For the set of [Attribute Instances]{.HTML_Keyboard} that are in S1, when [datasetId ]{.HTML_Variable}parameter is provided in the request: -::: - -::: B2plus -- Filter the Attribute instances based on the [datasetId ]{.HTML_Variable}parameter, i.e. keep only the Attribute instances whose [datasetId]{.HTML_Variable} is specified. The default Attribute instance is matched, if ["@none"]{.HTML_Code} is specified. -- If there is no Attribute instance whose [datasetId ]{.HTML_Variable}matches the value of the parameter, remove the complete Attribute from S1. -::: - -::: B1plus -- From the set of [Attribute Instances]{.HTML_Keyboard} that are in S1, include in their temporal representation only the Attribute instances (up to *lastN*) corresponding to the query's projection Attributes, or aggregated values of Attribute instances (if aggregated temporal representation is requested). -::: - -In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. - -#### 5.7.3.5 Output data {#taboutput-data-23 number="10.7.3.5"} - -A JSON-LD object representing the [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of the target Entity]{.HTML_Keyboard} as mandated by [clause 5.2.20](10-tabapi-operation-definition.md#tabentitytemporal). - -If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members. - -If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload. - -### 5.7.4 Query Temporal Evolution of Entities {#tabquery-temporal-evolution-of-entities number="10.7.4"} - -#### 5.7.4.1 Description {#tabdescription-24 number="10.7.4.1"} - -This operation allows querying the [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of Entities]{.HTML_Keyboard} present in an NGSI-LD system. It is similar to the operation defined by [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities) (Query Entities) with the addition of a temporal query. - -#### 5.7.4.2 Use case diagram {#tabuse-case-diagram-24 number="10.7.4.2"} - -A [Context Consumer]{.HTML_Keyboard} can retrieve the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in [Figure 5.7.4.2‑1](10-tabapi-operation-definition.md#Figure_5.7.4.2-1). - -::: FL -![](./media/image40.png){style="width:3.48611in;height:3.05556in"} -::: - -::: {#Figure_5.7.4.2-1 .TF} -Figure 5.7.4.2-1: Query Temporal Evolution of Entities use case -::: - -#### 5.7.4.3 Input data {#tabinput-data-24 number="10.7.4.3"} - -::: B1plus -- An NGSI-LD temporal query as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). Both type name (short hand string) and fully qualified type name (URI) are allowed. -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- A list (one or more) of Entity identifiers (optional). -- A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- An NGSI-LD query (called context source filter, to filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- A limit to the number of Entities to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -- A parameter (lastN) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional). -- A specified language filter as per [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -- A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional). -- A flag indicating whether to return the location of the EntityMap used within the operation (optional). -- A suggested lifetime for the EntityMap, if EntityMap is to be created (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (optional). -- A [datasetId]{.HTML_Variable} parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -- A preferred ordering of Entities retrieved - only the Entity member name ["id"]{.HTML_Code} can be used (Entity ordering attributes as defined by [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering)) (optional). -- A preferred collation setting to be used when applying ordering of Entities (optional). -- A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional). -::: - -In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. - -#### 5.7.4.4 Behaviour {#tabbehaviour-24 number="10.7.4.4"} - -::: B1plus -- If a temporal query is not provided then an error of type *BadRequestData* shall be raised. -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names, including at least one non-system Attribute; -::: - -::: B2 -c) NGSI-LD Query, including at least one non-system Attribute; -::: - -::: B2 -d) NGSI-LD GeoQuery; -::: - -::: B2 -e) local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). -::: - -::: B1 -If none of the above is provided, then an error of type *BadRequestData* shall be raised (too wide query). -::: - -::: B1plus -- If projection attributes or filter conditions indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, an error of type *BadRequestData* shall be raised. -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) an error of type *BadRequestData* shall be raised. -- If the ordering parameter is present and the execution of the operation is not limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)) then an error of type *BadRequestData* shall be raised. -- If the ordering parameter is present and refers an entity name other than ["id"]{.HTML_Code}, then an error of type *BadRequestData* shall be raised. -- If a preferred collation setting is present and it does not conform to a valid ICU collation (see IETF RFC 6067 [[36]](7-tabreferences.md#36)) then an error of type *BadRequestData* shall be raised. -- Term to URI expansion of type and Attribute names shall be observed mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- The *lastN* parameter refers to a number, *n*, of Attribute instances which shall correspond to the last *n* timestamps (in descending ordering) of the temporal property (by default *observedAt*) within the concerned temporal interval. -- Otherwise, -::: - -::: B2plus -- Let S be the set of selected Entities i.e. the query result set. -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided): -::: - -::: B3plus -- If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter. -- If an id pattern is provided, keep in S only those Entities whose id matches the id pattern. -- If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types. -- From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S4 be this new subset. -::: - -::: B2plus -- Implementations shall run a query that shall return the Temporal Evolution of the matching Entities (all Entities stored locally, in case only a local scope is specified); the logical steps to select the final result set of Entities, and the Attribute instances included as part of their temporal representation, are enumerated as follows: -::: - -::: B3plus -- If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter. -- If an id pattern is provided, keep in S only those Entities whose id matches the id pattern. -- If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types. -- From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset. -- If a values filter query is provided, from S1, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S2 be this new subset. -- If no values filter query is provided, then S2 is equal to S1. -- If geoquery is present, from S2, select those Entities whose *GeoProperty* instances meet the geospatial restrictions imposed by the geoquery (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); those geospatial restrictions shall be checked against the *GeoProperty* instances that are within the interval defined by the temporal query. Let S3 be this new subset. -- If no geoquery is provided, then S3 is equal to S2. -- If the Scope query is present, from S3, select those Entities whose Entity Scope instances match the Scope query (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.16](15-annex-c-informative-examples-of-using-the-api.md#c.5.16tabtemporal-scope-queries)). Let S4 be the new subset. -- If no Scope query is provided, then S4 is equal to S3. -::: - -::: B1plus -- If the ContextBroker implementation supports the use of EntityMaps then: -::: - -::: B2plus -- If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved: -::: - -::: B3plus -- If the resource cannot be found, or the data has expired, a new EntityMap shall be created. -- If the data has not expired, only the retrieved EntityMap shall be used to determine which Context Source Registrations match the Entity ID. -::: - -::: B2plus -- If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created. -::: - -::: B1plus -- Unless local scope is specified (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), for [Context Source Registrations]{.HTML_Keyboard} that match the query and support the "queryTemporal" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If an EntityMap is in use for this operation, and an EntityMap entry linked to a Context Source Registration is found, the location of the EntityMap shall be passed as part of the forwarded request. -::: - -::: B3plus -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. These filters then have to be applied after the Entity information from different Context Sources and local information, if there is any, has been aggregated. -::: - -::: B2plus -- For any **exclusive**, **redirect** and **inclusive** [Context Source Registrations]{.HTML_Keyboard} that match against the query, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an Entity Array. The returned result is then merged into S4 according to the algorithm defined in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- For any **auxiliary** [Context Source Registrations]{.HTML_Keyboard} that match against the query, the request is forwarded for remote querying by matching endpoints. Data from the Entity Array received is merged only into S4 when an Attribute instance, whose value of the timeproperty used for the temporal query, is not already present in S4. -::: - -::: B1plus -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, the following filters have to be applied on the aggregated Entities: -::: - -::: B2plus -- If a values filter query is provided, from S4, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S5 be this new subset. -- If no values filter query is provided, then S5 is equal to S4. -- If geoquery is present, from S5, select those Entities whose GeoProperty instances meet the geospatial restrictions imposed by the geoquery (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); those geospatial restrictions shall be checked against the GeoProperty instances that are within the interval defined by the temporal query. Let S6 be this new subset. -- If no geoquery is provided, then S6 is equal to S5. -- If the Scope query is present, from S6, select those Entities whose Entity Scope instances match the Scope query (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.16](15-annex-c-informative-examples-of-using-the-api.md#c.5.16tabtemporal-scope-queries)). Let S7 be the new subset. -- If no Scope query is provided, then S7 is equal to S6. -::: - -- ::: B1plus - Otherwise S7 is equal to S4. - ::: - -- ::: B1plus - If a *datasetId* parameter is provided, from S7, for all Entities, filter the Attribute instances based on the *datasetIds* specified in the parameter, i.e. keep only the Attribute instances whose*datasetId* is specified. The default Attribute instance is matched, if ["@none"]{.HTML_Code} is specified. Remove all Attributes without remaining Attribute instances. Let S8 be this new subset. - ::: - -- ::: B1plus - If no *datasetId* is provided then S8 equals to S7. - ::: - -- ::: B1plus - From the set of Entities that are in S8, include in their temporal representation only the Attribute instances (up to *lastN*) corresponding to the query's projection Attributes, or aggregated values of Attribute instances (if aggregated temporal representation is requested), and which meet the temporal, query and geoquery restrictions. - ::: - - ::: B1plus - If an aggregated temporal representation is requested and any of the requested Attributes is not eligible for at least one of the aggregation methods specified in the request parameters, then an error of type *InvalidRequest* shall be raised. - ::: - -- ::: B1plus - Pagination logic shall be in place as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). - ::: - -- ::: B1plus - If in the process of obtaining the query result it is necessary to issue a [Context Source]{.HTML_Keyboard} discovery operation, the same [Context Source]{.HTML_Keyboard} filter input parameter (if present) shall be propagated. - ::: - -#### 5.7.4.5 Output Data {#taboutput-data-24 number="10.7.4.5"} - -A JSON-LD array representing the matching entities as defined by [clause 5.2.21](10-tabapi-operation-definition.md#tabtemporalquery) and selected according to the behaviour described by [clause 5.7.4.4](10-tabapi-operation-definition.md#tabbehaviour-24). - -If Entity ordering is specified (see [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering)), then the JSON-LD array returned shall be ordered according to the member names specified. - -If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members. - -If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload. - -### 5.7.5 Retrieve Available Entity Types {#tabretrieve-available-entity-types number="10.7.5"} - -#### 5.7.5.1 Description {#tabdescription-25 number="10.7.5.1"} - -This operation allows retrieving a list of NGSI-LD entity types for which entity instances exist within the NGSI-LD system. - -#### 5.7.5.2 Use case diagram {#tabuse-case-diagram-25 number="10.7.5.2"} - -A *Context Consumer* can retrieve a list of NGSI-LD entity types from the system as shown in [Figure 5.7.5.2‑1](10-tabapi-operation-definition.md#Figure_5.7.5.2-1). - -::: FL -![](./media/image41.png){style="width:3.45833in;height:3.02778in"} -::: - -::: {#Figure_5.7.5.2-1 .TF} -Figure 5.7.5.2-1: Retrieve Available Entity Types use case -::: - -#### 5.7.5.3 Input data {#tabinput-data-25 number="10.7.5.3"} - -::: B1plus -- An optional JSON-LD context. -::: - -#### 5.7.5.4 Behaviour {#tabbehaviour-25 number="10.7.5.4"} - -::: B1plus -- Return a JSON-LD object representing the list of entity types, as mandated by [clause 5.2.24](10-tabapi-operation-definition.md#tabentitytypelist), for which entity instances exist within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects, in particular the distributed behaviour. -::: - -#### 5.7.5.5 Output data {#taboutput-data-25 number="10.7.5.5"} - -A JSON-LD object representing the list of available entity types, as mandated by [clause 5.2.24](10-tabapi-operation-definition.md#tabentitytypelist). - -### 5.7.6 Retrieve Details of Available Entity Types {#tabretrieve-details-of-available-entity-types number="10.7.6"} - -#### 5.7.6.1 Description {#tabdescription-26 number="10.7.6.1"} - -This operation allows retrieving a list with a detailed representation of NGSI-LD entity types for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided *\@context*) and the attribute names that existing instances of this entity type have. - -#### 5.7.6.2 Use case diagram {#tabuse-case-diagram-26 number="10.7.6.2"} - -A *Context Consumer* can retrieve a list with a detailed representation of NGSI-LD entity types from the system as shown in [Figure 5.7.6.2‑1](10-tabapi-operation-definition.md#Figure_5.7.6.2-1). - -::: FL -![](./media/image42.png){style="width:3.47222in;height:3.05556in"} -::: - -::: {#Figure_5.7.6.2-1 .TF} -Figure 5.7.6.2-1: Retrieve Details of Available Entity Types use case -::: - -#### 5.7.6.3 Input data {#tabinput-data-26 number="10.7.6.3"} - -::: B1plus -- An optional JSON-LD context. -::: - -#### 5.7.6.4 Behaviour {#tabbehaviour-26 number="10.7.6.4"} - -::: B1plus -- Return a list of JSON-LD objects representing the details of available entity types as mandated by [clause 5.2.25](10-tabapi-operation-definition.md#tabentitytype) for which entity instances exist within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects, in particular the distributed behaviour. -::: - -#### 5.7.6.5 Output data {#taboutput-data-26 number="10.7.6.5"} - -A list of JSON-LD objects representing the details of available entity types as mandated by [clause 5.2.25](10-tabapi-operation-definition.md#tabentitytype). - -### 5.7.7 Retrieve Available Entity Type Information {#tabretrieve-available-entity-type-information number="10.7.7"} - -#### 5.7.7.1 Description {#tabdescription-27 number="10.7.7.1"} - -This operation allows retrieving detailed entity type information about a specified NGSI-LD entity type for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided *\@context*), the count of available entity instances and details about attributes that existing instances of this entity type have, including their name (as short name if available in the provided *\@context*) and a list of types the attribute can have (e.g. *Property*, *Relationship* or *GeoProperty*). - -#### 5.7.7.2 Use case diagram {#tabuse-case-diagram-27 number="10.7.7.2"} - -A *Context Consumer* can retrieve a detailed representation of a specified NGSI-LD entity type from the system as shown in [Figure 5.7.7.2‑1](10-tabapi-operation-definition.md#Figure_5.7.7.2-1). - -::: FL -![](./media/image43.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.7.7.2-1 .TF} -Figure 5.7.7.2-1: Retrieve Available Entity Type Information use case -::: - -#### 5.7.7.3 Input data {#tabinput-data-27 number="10.7.7.3"} - -::: B1plus -- Entity type name for which detailed information is to be retrieved. -- An optional JSON-LD context. -::: - -#### 5.7.7.4 Behaviour {#tabbehaviour-27 number="10.7.7.4"} - -::: B1plus -- Return a JSON-LD object representing the details of the specified entity type as mandated by [clause 5.2.26](10-tabapi-operation-definition.md#tabentitytypeinfo), for which instances exist within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects. -::: - -#### 5.7.7.5 Output data {#taboutput-data-27 number="10.7.7.5"} - -A JSON-LD object representing the details of the specified entity type as mandated by [clause 5.2.26](10-tabapi-operation-definition.md#tabentitytypeinfo). - -### 5.7.8 Retrieve Available Attributes {#tabretrieve-available-attributes number="10.7.8"} - -#### 5.7.8.1 Description {#tabdescription-28 number="10.7.8.1"} - -This operation allows retrieving a list of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system. - -#### 5.7.8.2 Use case diagram {#tabuse-case-diagram-28 number="10.7.8.2"} - -A *Context Consumer* can retrieve a list of NGSI-LD attributes from the system as shown in [Figure 5.7.8.2‑1](10-tabapi-operation-definition.md#Figure_5.7.8.2-1). - -::: FL -![](./media/image44.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.7.8.2-1 .TF} -Figure 5.7.8.2-1: Retrieve Available Attributes use case -::: - -#### 5.7.8.3 Input data {#tabinput-data-28 number="10.7.8.3"} - -::: B1plus -- An optional JSON-LD context. -::: - -#### 5.7.8.4 Behaviour {#tabbehaviour-28 number="10.7.8.4"} - -::: B1plus -- Return a JSON-LD object representing the list of attributes as mandated by [clause 5.2.27](10-tabapi-operation-definition.md#tabattributelist) that belong to entity instances existing within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects, in particular the distributed behaviour. -::: - -#### 5.7.8.5 Output data {#taboutput-data-28 number="10.7.8.5"} - -A JSON-LD object representing the list of available attributes as mandated by [clause 5.2.27](10-tabapi-operation-definition.md#tabattributelist). - -### 5.7.9 Retrieve Details of Available Attributes {#tabretrieve-details-of-available-attributes number="10.7.9"} - -#### 5.7.9.1 Description {#tabdescription-29 number="10.7.9.1"} - -This operation allows retrieving a list with a detailed representation of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided *\@context*) and the type names for which entity instances exist that have the respective attribute. - -#### 5.7.9.2 Use case diagram {#tabuse-case-diagram-29 number="10.7.9.2"} - -A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in [Figure 5.7.9.2‑1](10-tabapi-operation-definition.md#Figure_5.7.9.2-1). - -::: FL -![](./media/image45.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.7.9.2-1 .TF} -Figure 5.7.9.2-1: Retrieve Details of Available Attributes use case -::: - -#### 5.7.9.3 Input data {#tabinput-data-29 number="10.7.9.3"} - -An optional JSON-LD context. - -#### 5.7.9.4 Behaviour {#tabbehaviour-29 number="10.7.9.4"} - -Return a list of JSON-LD objects representing the details of available attributes as mandated by [clause 5.2.28](10-tabapi-operation-definition.md#tabattribute) (restricted to the elements *id*, *type*, *attributeName* and *typeNames*) that belong to entity instances existing within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects, in particular the distributed behaviour. - -#### 5.7.9.5 Output data {#taboutput-data-29 number="10.7.9.5"} - -A list of JSON-LD objects representing the details of available attributes as mandated by [clause 5.2.28](10-tabapi-operation-definition.md#tabattribute) (restricted to the elements id, type, attributeName and typeNames). - -### 5.7.10 Retrieve Available Attribute Information {#tabretrieve-available-attribute-information number="10.7.10"} - -#### 5.7.10.1 Description {#tabdescription-30 number="10.7.10.1"} - -This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided *\@context*) and the type names for which entity instances exist that have the respective attribute, a count of available attribute instances and a list of types the attribute can have (e.g. *Property*, *Relationship* or *GeoProperty*). - -#### 5.7.10.2 Use case diagram {#tabuse-case-diagram-30 number="10.7.10.2"} - -A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in [Figure 5.7.10.2‑1](10-tabapi-operation-definition.md#Figure_5.7.10.2-1). - -::: FL -![](./media/image46.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.7.10.2-1 .TF} -Figure 5.7.10.2-1: Retrieve Available Attribute Information use case -::: - -#### 5.7.10.3 Input data {#tabinput-data-30 number="10.7.10.3"} - -::: B1plus -- Name of the attribute for which detailed information is to be retrieved. -- An optional JSON-LD context. -::: - -#### 5.7.10.4 Behaviour {#tabbehaviour-30 number="10.7.10.4"} - -Return a JSON-LD object representing the details of available attributes as mandated by [clause 5.2.28](10-tabapi-operation-definition.md#tabattribute) that belong to entity instances existing within the NGSI-LD system. See [clause 5.7.11](10-tabapi-operation-definition.md#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes) for architecture-related implementation aspects, in particular the distributed behaviour. - -#### 5.7.10.5 Output data {#taboutput-data-30 number="10.7.10.5"} - -A JSON-LD object representing the details of available attributes as mandated by [clause 5.2.28](10-tabapi-operation-definition.md#tabattribute). - -### 5.7.11 Architecture-related aspects of retrieval of Entity Types and Attributes {#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes number="10.7.11"} - -Retrieving information about available types or attributes can be an expensive operation depending on the scale and architectural design decisions of the NGSI-LD system. This is in particular the case for retrieving the information about all available entity types and attributes related to all entity information available in an NGSI-LD system. Especially in the case of distributed architecture [(clause 4.3.3](9-tabcontext-information-management-framework.md#tabdistributed-architecture)) and federated architecture [(clause 4.3.4](9-tabcontext-information-management-framework.md#tabfederated-architecture)) checking all entities can be so expensive that it can become practically infeasible. - -Therefore, implementations may only take into account only information that is available or can be derived from a local datastore and the [Context Registry]{.HTML_Keyboard}, when implementing the retrieval of available entity types and attributes, as described in clauses [5.7.5](10-tabapi-operation-definition.md#tabretrieve-available-entity-types), [5.7.6](10-tabapi-operation-definition.md#tabretrieve-details-of-available-entity-types), [5.7.7](10-tabapi-operation-definition.md#tabretrieve-available-entity-type-information), [5.7.8](10-tabapi-operation-definition.md#tabretrieve-available-attributes), [5.7.9](10-tabapi-operation-definition.md#tabretrieve-details-of-available-attributes) and [5.7.10](10-tabapi-operation-definition.md#tabretrieve-available-attribute-information). Context registrations do not always reflect which entity instances are actually available from a [Context Source]{.HTML_Keyboard} at a particular point in time, but only which entity instances are possibly available from a [Context Source]{.HTML_Keyboard}, thus in this case the information about available entity types and attributes is to be interpreted as "possibly available". Also, context registrations can have different granularities, i.e. they possibly only contain entity type or attribute information, and thus the provided information about available entity types and attributes is possibly incomplete as a result. In particular the *attributeNames* in the *EntityType* data structure [(clause 5.2.25](10-tabapi-operation-definition.md#tabentitytype)), the *attributeDetails* in the *EntityTypeInfo* data structure [(clause 5.2.26](10-tabapi-operation-definition.md#tabentitytypeinfo)), and the *attributeTypes* and *typeNames* in the *Attribute* data structure [(clause 5.2.27](10-tabapi-operation-definition.md#tabattributelist)) may be provided as empty arrays if the information is not included in the respective context registration. Implementations may also provide estimates for the entity count or attribute count instead of the accurate count. - -As an alternative to relying on local information only, the request can be forwarded to all [Context Sources]{.HTML_Keyboard} which support the respective operation according to the [Context Source Registration]{.HTML_Keyboard} describing them. In this case the returned lists are merged with the local list of entity types before returning them. This approach is more expensive but leads to a more accurate result. - -## 5.8 Context Information Subscription {#tabcontext-information-subscription number="10.8"} - -### 5.8.1 Create Subscription {#tabcreate-subscription number="10.8.1"} - -#### 5.8.1.1 Description {#tabdescription-31 number="10.8.1.1"} - -This operation allows creating a new subscription. - -#### 5.8.1.2 Use case diagram {#tabuse-case-diagram-31 number="10.8.1.2"} - -A *Context Subscriber* can create a subscription to receive context updates within an NGSI-LD system as shown in [Figure 5.8.1.2‑1](10-tabapi-operation-definition.md#Figure_5.8.1.2-1). - -::: FL -![](./media/image47.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.8.1.2-1 .TF} -Figure 5.8.1.2-1: Create subscription use case -::: - -#### 5.8.1.3 Input data {#tabinput-data-31 number="10.8.1.3"} - -::: B1plus -- A data structure (represented in JSON-LD) conforming to the *Subscription* data type as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). -::: - -#### 5.8.1.4 Behaviour {#tabbehaviour-31 number="10.8.1.4"} - -::: B1plus -- If the data types, cardinalities and restrictions expressed by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription) are not met, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint already knows about this Subscription, as there is an existing Subscription whose id (URI) is equivalent, an error of type *AlreadyExists* shall be raised. -- If the subscription document does not include a Subscription identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. -- Then, implementations shall add a new Subscription. The behaviour for corresponding notifications shall be as per [clause 5.8.6](10-tabapi-operation-definition.md#tabnotification-behaviour). The parameters of the created Subscription shall be configured as follows: -::: - -::: B2plus -- The Subscription expiration date shall be equal to the value of the *expiresAt* member. If the expiration timestamp provided represents a moment before the current date and time, then an error of type *BadRequestData* shall be raised. If there is no *expiresAt* member the Subscription shall be considered as perpetual. -- If the value of the *isActive* field is not included or is *true* then the initial status of the Subscription shall be set to ["active"]{.HTML_Code}. -- If the value of the *isActive* field is *false*, then the initial status of the Subscription shall be set to ["paused"]{.HTML_Code}. -- If present, the subscribed entities shall be those matching the conditions expressed under the *EntitySelector*, as defined in [clause 5.2.33](10-tabapi-operation-definition.md#tabentityselector). -- Watched Attributes shall be those Attributes (subject to [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction) Term to URI expansion) pertaining to the subscribed entities (if present) and conveyed through the *watchedAttributes* member. Watched Attributes are those that trigger a new notification when they are changed. A non-present *watchedAttributes* member means that all Attributes shall be watched. If no subscribed entities have been specified, all entities with attributes matching at least one member of *watchedAttributes* are subscribed to. -- The *\@context* to be used for sending Notifications related to this Subscription shall be the one specified in the *jsonldContext* field. If not present, the *jsonldContext* field shall be initialized with the *\@context* applicable for the Subscription (if *\@context* is also not present in the Subscription, see [clause 5.5.5](10-tabapi-operation-definition.md#tabdefault-context-assignment)). When the remote JSON-LD *\@context* referenced by the *jsonldContext* field is not available implementations shall raise an error of type *LdContextNotAvailable*. If the remote JSON-LD *\@context* referenced by the *jsonldContext* field is invalid, implementations shall raise an error of type *BadRequestData*. -- Based on the content of the Subscription, a [Context Source Registration]{.HTML_Keyboard} Subscription shall be created [(clause 5.11.2](10-tabapi-operation-definition.md#tabcreate-context-source-registration-subscription)). The mapping of the *id* of the Subscription to the returned *subscriptionId* of the [Context Source Registration]{.HTML_Keyboard} Subscription shall be stored to enable updating or deleting the [Context Source Registration]{.HTML_Keyboard} Subscription in case of changes to the Subscription. -::: - -::: B1plus -- If the subscription defines a *timeInterval* member, a Notification shall be sent periodically, when the time interval (in seconds) specified in such value field is reached, regardless of Attribute changes. -- If *timeInterval* is not defined, whenever there is a change in the watched Attribute nodes (Properties or Relationships) of the concerned Entities, implementations shall post a new Notification as per the rules defined by [clause 5.8.6](10-tabapi-operation-definition.md#tabnotification-behaviour). -- If *localOnly=false,* each time a [Context Source]{.HTML_Keyboard} Notification with the *subscriptionId* of the previously created [Context Source Registration]{.HTML_Keyboard} Subscription is received, implementations shall do the following: -::: - -::: B2plus -- For any **exclusive**, **redirect** and **inclusive** [Context Source Registration]{.HTML_Keyboard} received as part of the notification, implementation shall do the following depending on the *triggerReason*: -::: - -::: B3plus -- If the *triggerReason* is ["newlyMatching"]{.HTML_Code} and the [Context Source Registration]{.HTML_Keyboard} indicates support for the Create Subscription operation, a copy of the original Subscription shall be reduced to what is matched by the registration information. If the *splitEntities* member is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the members *q*, *geoQ* and *scopeQ* shall be removed from the created copy of the original Subscription. Also from the *notification* member, the *attributes*, *pick* and *omit* members are to be removed. The copied Subscription is then forwarded to the [Context Source]{.HTML_Keyboard} as a new Subscription where the notification endpoint is set to that of the local Broker. The mapping of the received *subscriptionId* with the own Subscription identifier is stored to enable forwarding received notifications to the original subscriber. In addition, a mapping of the id of the [Context Source Registration]{.HTML_Keyboard} to the received *subscriptionId* is stored, to enable updating or deleting the subscription in case of changes. -- If the *triggerReason* is ["updated"]{.HTML_Code} and the [Context Source Registration]{.HTML_Keyboard} indicates support for the Update Subscription operation, an update of the original Subscription, reduced to what is matched by the registration information, shall be created. If the *splitEntities* member is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the members *q*, *geoQ* and *scopeQ* shall be removed from the updated Subscription. Also from the *notification* member the *attributes*, *pick* and *omit* members are to be removed. The updated Subscription is then forwarded to the [Context Source]{.HTML_Keyboard} with the *subscriptionId* related to the [Context Source Registration]{.HTML_Keyboard}. As an optimization, an implementation may keep the originally forwarded [Context Source Registration]{.HTML_Keyboard} and compare with the new one to only forward the update, if there was a relevant change. -- If the *triggerReason* is ["noLongerMatching"]{.HTML_Code} and the [Context Source Registration]{.HTML_Keyboard} indicates support for the delete Subscription operation, a delete Subscription shall be forwarded to the [Context Source]{.HTML_Keyboard} with the *subscriptionId* related to the [Context Source Registration]{.HTML_Keyboard}. -::: - -::: B1plus -- Implementations shall ensure that, when the Subscription expiration date is due, the status of the Subscription changes automatically to "[expired"]{.HTML_Code}, so that notifications will no longer be sent. -::: - -#### 5.8.1.5 Output data {#taboutput-data-31 number="10.8.1.5"} - -A URI identifying the newly created Subscription. - -### 5.8.2 Update Subscription {#tabupdate-subscription number="10.8.2"} - -#### 5.8.2.1 Description {#tabdescription-32 number="10.8.2.1"} - -This operation allows updating an existing subscription. - -#### 5.8.2.2 Use case diagram {#tabuse-case-diagram-32 number="10.8.2.2"} - -A *Context Subscriber* can update an existing subscription within an NGSI-LD system as shown in [Figure 5.8.2.2‑1](10-tabapi-operation-definition.md#Figure_5.8.2.2-1). - -::: FL -![](./media/image48.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.8.2.2-1 .TF} -Figure 5.8.2.2-1: Update subscription use case -::: - -#### 5.8.2.3 Input data {#tabinput-data-32 number="10.8.2.3"} - -::: B1plus -- Subscription identifier (URI), the target subscription. -- A JSON-LD document representing a Subscription Fragment. -::: - -#### 5.8.2.4 Behaviour {#tabbehaviour-32 number="10.8.2.4"} - -::: B1plus -- If the Subscription id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD System does not know about the target Subscription, because there is no existing Subscription whose id (URI) is equivalent, an error of type *ResourceNotFound* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If the data types and restrictions expressed by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription) are not met by the *Subscription Fragment*, then an error of type *BadRequestData* shall be raised. -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- If the *jsonldContext* field is present and the referenced JSON-LD *\@context* is not available, implementations shall raise an error of type *LdContextNotAvailable*. If the referenced JSON-LD *\@context* is invalid, implementations shall raise an error of type *BadRequestData*. -- Then, implementations shall modify the target Subscription as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour). -- Finally, the following extra behaviour shall be observed when updating Subscriptions: -::: - -::: B2plus -- If *isActive* is equal to *true* and *expiresAt* is not present, then *status* shall be updated to ["active",]{.HTML_Code} if and only if, the previous value of *status* was different than ["expired"]{.HTML_Code}. -- If *isActive* is equal to *true* and *expiresAt* corresponds to a *DateTime* in the future, then *status* shall be updated to ["active"]{.HTML_Code}. -- If *isActive* is equal to *false* and *expiresAt* is not present, then *status* shall be updated to ["paused]{.HTML_Code}", if and only if, the previous value of *status* was different than ["expired"]{.HTML_Code}. -- If only *expiresAt* is included and refers to a *DateTime* in the future, then *status* shall be updated to ["active",]{.HTML_Code} if and only if the previous value of *status* was ["expired"]{.HTML_Code}. -- If *expiresAt* is included but referring to a *DateTime* in the past, then a *BadRequestData* error shall be raised, regardless the value of *isActive*. -- Based on the mapping of the Subscription to its respective [Context Source Registration]{.HTML_Keyboard} Subscription (see [clause 5.8.1.4](10-tabapi-operation-definition.md#tabbehaviour-31)), that [Context Source Registration]{.HTML_Keyboard} Subscription shall be updated [(clause 5.11.3](10-tabapi-operation-definition.md#tabupdate-context-source-registration-subscription)). -::: - -#### 5.8.2.5 Output data {#taboutput-data-32 number="10.8.2.5"} - -None. - -### 5.8.3 Retrieve Subscription {#tabretrieve-subscription number="10.8.3"} - -#### 5.8.3.1 Description {#tabdescription-33 number="10.8.3.1"} - -This operation allows retrieving an existing subscription. - -#### 5.8.3.2 Use case diagram {#tabuse-case-diagram-33 number="10.8.3.2"} - -A *Context Subscriber* can retrieve a specific subscription from an NGSI-LD system as shown in [Figure 5.8.3.2‑1](10-tabapi-operation-definition.md#Figure_5.8.3.2-1). - -::: FL -![](./media/image49.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.8.3.2-1 .TF} -Figure 5.8.3.2-1: Retrieve subscription use case -::: - -#### 5.8.3.3 Input data {#tabinput-data-33 number="10.8.3.3"} - -Id (URI) of the subscription to be retrieved (target subscription). - -#### 5.8.3.4 Behaviour {#tabbehaviour-33 number="10.8.3.4"} - -::: B1plus -- If the subscription Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the identifier provided does not correspond to any existing subscription in the system then an error of type *ResourceNotFound* shall be raised. -- Otherwise, implementations shall query the subscriptions and obtain the subscription data to be returned to the caller. -::: - -#### 5.8.3.5 Output data {#taboutput-data-33 number="10.8.3.5"} - -A JSON-LD object representing the subscription details as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). - -### 5.8.4 Query Subscriptions {#tabquery-subscriptions number="10.8.4"} - -#### 5.8.4.1 Description {#tabdescription-34 number="10.8.4.1"} - -This operation allows querying existing Subscriptions. - -#### 5.8.4.2 Use case diagram {#tabuse-case-diagram-34 number="10.8.4.2"} - -A [Context Consumer]{.HTML_Keyboard} can query the existent Subscriptions from an NGSI-LD system as shown in [Figure 5.8.4.2‑1](10-tabapi-operation-definition.md#Figure_5.8.4.2-1). - -::: FL -![](./media/image50.png){style="width:3.48611in;height:3.05556in"} -::: - -::: {#Figure_5.8.4.2-1 .TF} -Figure 5.8.4.2-1: Query subscriptions use case -::: - -#### 5.8.4.3 Input data {#tabinput-data-34 number="10.8.4.3"} - -A limit to the number of subscriptions to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). - -#### 5.8.4.4 Behaviour {#tabbehaviour-34 number="10.8.4.4"} - -::: B1plus -- The NGSI-LD system shall list all the existing subscriptions up to the limit specified as input data. If no limit is specified the number of subscriptions retrieved may depend on the implementation. -- Pagination logic shall be in place as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -::: - -#### 5.8.4.5 Output data {#taboutput-data-34 number="10.8.4.5"} - -A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). - -### 5.8.5 Delete Subscription {#tabdelete-subscription number="10.8.5"} - -#### 5.8.5.1 Description {#tabdescription-35 number="10.8.5.1"} - -This operation allows deleting an existing subscription. - -#### 5.8.5.2 Use case diagram {#tabuse-case-diagram-35 number="10.8.5.2"} - -A *Context Subscriber* can delete a subscription within an NGSI-LD system as shown in [Figure 5.8.5.2‑1](10-tabapi-operation-definition.md#Figure_5.8.5.2-1). - -::: FL -![](./media/image51.png){style="width:3.47222in;height:2.83333in"} -::: - -::: {#Figure_5.8.5.2-1 .TF} -Figure 5.8.5.2-1: Delete subscription use case -::: - -#### 5.8.5.3 Input data {#tabinput-data-35 number="10.8.5.3"} - -A subscription identifier (URI). - -#### 5.8.5.4 Behaviour {#tabbehaviour-35 number="10.8.5.4"} - -::: B1plus -- If the subscription Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the subscription id provided does not correspond to any existing subscription in the system, then an error of type *ResourceNotFound* shall be raised. -- Otherwise, implementations shall delete the Subscription and no longer perform notifications concerning such Subscription. -- Using the mapping of the own Subscription identifier to each of the *subscriptionId* of a subscription to a [Context Source]{.HTML_Keyboard}, a delete Subscription shall be forwarded to each such [Context Source]{.HTML_Keyboard}, if the delete Subscription operation is supported as indicated in the corresponding [Context Source Registration]{.HTML_Keyboard}: -::: - -::: B2plus -- Based on the mapping of the Subscription to its respective [Context Source Registration]{.HTML_Keyboard} Subscription (see [clause 5.8.1.4](10-tabapi-operation-definition.md#tabbehaviour-31)), that [Context Source Registration]{.HTML_Keyboard} Subscription shall be deleted [(clause 5.11.6](10-tabapi-operation-definition.md#tabdelete-context-source-registration-subscription)). -::: - -#### 5.8.5.5 Output data {#taboutput-data-35 number="10.8.5.5"} - -None. - -### 5.8.6 Notification behaviour {#tabnotification-behaviour number="10.8.6"} - -A notification is a message that allows a subscriber to be aware of the changes in subscribed Entities. Implementations shall exhibit the following behaviour: - -::: B1plus -- Notifications shall only be sent if and only if the status of the corresponding subscription (*subscription.status*) is "[active"]{.HTML_Code}, i.e. not "[paused"]{.HTML_Code} nor "[expired"]{.HTML_Code}. -- If a Subscription defines a *timeInterval* member, a Notification shall be sent periodically, when the time interval (in seconds) specified in such value field is reached, regardless of Attribute changes. The notification message shall include all the subscribed Entities that match the query, geoquery and Scope query conditions. If none of query, geoquery and Scope query are defined, then all subscribed Entities shall be included. For each entity in the notification, only the Attribute instances are to be included that match the *datasetId* member in Subscription. If there are no matching Entities, no Notification is sent. -- If a Subscription does not define a *timeInterval* term, the notification shall be sent whenever there is a change in the watched Attributes. An Attribute is considered to change when any of the members (including children) in its corresponding JSON-LD node is updated with a value different than the existing one. The notification message shall include all the subscribed Entities that changed and that match (as mandated by clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language), [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) and [4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)) the query, geoquery and Scope query conditions. If query, geoquery and scopeQuery are all not defined then all subscribed Entities that changed shall be included. If, for an Entity, there are multiple instances of the *GeoProperty* on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions. For each entity in the notification, only the Attribute instances are to be included that match the *datasetId* member in Subscription. Finally, if a [Context Source]{.HTML_Keyboard} filter is defined, then only the subscribed Entities whose origin [Context Source]{.HTML_Keyboard} matches the referred filter shall be included. -- If a Notification with a *subscriptionId* is received that has a mapping to a local Subscription identifier, the Notification shall be copied. If the *splitEntities* member of the local Subscription is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities: -::: - -::: B2plus -- The Entities contained in the data member of the Notification shall be retrieved locally and from all Context Sources that have information about these Entities, except for the one from which the Notification has been received. -- The retrieved Entities then shall be merged with the Entities in the data member. -- All Entities that do not match the query, geoquery and Scope query conditions of the local Subscription shall be removed from the data member. -::: - -::: B1plus -- If there are Entities in the *data* member of the Notification copy, the Notification copy shall be forwarded to the Notification endpoint specified in the local Subscription, using this local Subscription identifier instead of the *subscriptionId* **received**. -- A Notification shall be sent as follows: -::: - -::: B2plus -- The structure of the notification message shall be as mandated by [clause 5.3.1](10-tabapi-operation-definition.md#tabnotification). -- The *\@context* to be used is the one specified in the *jsonldContext* field of the corresponding Subscription. -- The Attributes included (*Properties* or *Relationships*) shall be those specified by the *notification.attributes* member in the Subscription data type [(clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription)). Term to URI expansion shall be observed [(clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)). The absence of the *notification.attributes* member of a Subscription means that all Attributes shall be included. If the notification was triggered by the deletion of an Entity and the *notification.showChanges* member is not set to *true*, only the *deletedAt* system property shall be provided. In case *notification.sysAttrs* is set to *true*, also *createdAt* and *modifiedAt* shall be provided. -- If an Attribute has been deleted, only the name of the attribute as key and the URI ["urn:ngsi-ld:null"]{.HTML_Code} as value shall be provided, unless more information is required. The latter is the case, if: -::: - -::: B3plus -- a *datasetId* needs to be provided; -- *the notification.sysAttrs* is set to *true* and thus the system generated sub-attributes (see [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)) have to be provided; -- *notification.showChanges* is set to *true* and thus a previous value or object has to be provided. -::: - -::: B2 -In all such cases, a JSON object with all the required information is provided, where the *value* or the *object* is set to the URI ["urn:ngsi-ld:null"]{.HTML_Code} respectively or, in case of a *LanguageProperty*, the *languageMap* is set to [{"@none": "urn:ngsi-ld:null"}]{.HTML_Code}. -::: - -::: B2plus -- [If the ]{.ondemand_CHAR_color_000000}*notification.format*[member value is set, the representation of the entities changes:]{.ondemand_CHAR_color_000000} -::: - -::: B3plus -- If the *notification.format* is set to ["concise" ]{.HTML_Code}then a concise representation of the entities shall be provided as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation). -- If the *notification.format* is set to ["simplified"]{.HTML_Code} (or ["keyValues"]{.HTML_Code} as a synonym), then a simplified representation of the entities (as mandated by [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation)) shall be provided. -- Otherwise the normalized format as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation) shall be used. -::: - -::: B2plus -- [If the ]{.ondemand_CHAR_color_000000}*notification.pick*[member value ]{.ondemand_CHAR_color_000000}is set, every Entity within the payload body is reduced down to only contain the defined entity members listed. -- [If the ]{.ondemand_CHAR_color_000000}*notification.omit*[member value]{.ondemand_CHAR_color_000000} is set, the defined entity members listed are removed from each Entity within the payload. -- [If the ]{.ondemand_CHAR_color_000000}*notification.join*[member value is set then ]{.ondemand_CHAR_color_000000}[Linked Entity]{.HTML_Keyboard}**[retrieval]{.ondemand_CHAR_color_000000}**[(as mandated by clause ]{.ondemand_CHAR_color_000000}4.5.23[) shall be provided. ]{.ondemand_CHAR_color_000000} -- If the *ngsildConformance* field of the corresponding Subscription is set, the notification shall undergo a backwards compatibility operation as defined by [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads) and be amended to conform to the supplied version of the NGSI-LD specification. -- [A Notification shall be sent (as mandated by each concrete binding and including any optional ]{.ondemand_CHAR_color_000000}*endpoint.receiverInfo*[defined by clause ]{.ondemand_CHAR_color_000000}5.2.22[) to the endpoint specified by the ]{.ondemand_CHAR_color_000000}*endpoint.uri*[member of the notification structure defined by ]{.ondemand_CHAR_color_000000}clause [5.2.14. The Notification content shall be ]{.ondemand_CHAR_color_000000}JSON[by default. However, this can be changed to ]{.ondemand_CHAR_color_000000}JSON-LD or GeoJSON[by means of the ]{.ondemand_CHAR_color_000000}*endpoint.accept*[member.]{.ondemand_CHAR_color_000000} -- The *notification.timesSent* member shall be incremented by one. -- The *notification.lastNotification* member shall be updated with a timestamp representing the current date and time. -- If the response to the notification request is 200 OK then implementations shall: -::: - -::: B3plus -- Update *notification.lastSuccess* with a timestamp representing the current date and time. -- Update *notification.status* to ["ok"]{.HTML_Code}. -::: - -::: B2plus -- [If the response to the notification request is different than 200 ]{.ondemand_CHAR_color_000000}OK[then implementations shall:]{.ondemand_CHAR_color_000000} -::: - -::: B3plus -- Update *notification.lastFailure* with a timestamp representing the current date and time. -- Update *notification. Status* to ["failed"]{.HTML_Code}. -::: - -## 5.9 Context Source Registration {#tabcontext-source-registration number="10.9"} - -### 5.9.1 Introduction {#tabintroduction-18 number="10.9.1"} - -As described in [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration), [Context Source Registrations]{.HTML_Keyboard} have a similar structure as Entities and are generally handled in the same way. However, there are some aspects that are specific to Registrations, in particular with respect to the handling of required properties. Thus, the operation descriptions for Registrations reference the respective operations for Entities and in addition specify any deviations and additions that are necessary for handling [Context Source Registrations]{.HTML_Keyboard}. - -[Context Source Registrations]{.HTML_Keyboard} either contain information about [Context Sources]{.HTML_Keyboard} providing the latest information or about [Context Sources]{.HTML_Keyboard} providing temporal information, but not both. [Context Sources]{.HTML_Keyboard} that can provide both thus have to use two separate [Context Source Registrations]{.HTML_Keyboard}. If no temporal query is present, only [Context Source Registrations]{.HTML_Keyboard} for [Context Sources]{.HTML_Keyboard} providing latest information are returned, i.e. those which do not specify time intervals used for temporal queries. If a temporal query is present in a request for [Context Source Registrations]{.HTML_Keyboard}, only those [Context Source Registrations]{.HTML_Keyboard} that have a matching time interval are returned. - -### 5.9.2 Register Context Source {#tabregister-context-source number="10.9.2"} - -#### 5.9.2.1 Description {#tabdescription-36 number="10.9.2.1"} - -This operation allows registering a context source within an NGSI-LD system. - -#### 5.9.2.2 Use case diagram {#tabuse-case-diagram-36 number="10.9.2.2"} - -A *Context Provider* can register one or more context sources within an NGSI-LD system as shown in [Figure 5.9.2.2‑1](10-tabapi-operation-definition.md#Figure_5.9.2.2-1). - -::: FL -![](./media/image52.png){style="width:3.47222in;height:2.93056in"} -::: - -::: {#Figure_5.9.2.2-1 .TF} -Figure 5.9.2.2-1: Register context source use case -::: - -#### 5.9.2.3 Input data {#tabinput-data-36 number="10.9.2.3"} - -A data structure conforming to the *CSourceRegistration* data type as mandated by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration). - -#### 5.9.2.4 Behaviour {#tabbehaviour-36 number="10.9.2.4"} - -Implementations shall generally exhibit the behaviour described in [clause 5.6.1.4](10-tabapi-operation-definition.md#tabbehaviour), but instead of any type of entities only [Context Source Registrations]{.HTML_Keyboard} can be provided and the following exceptions shall apply: - -::: B1plus -- If the data types and restrictions expressed by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration) are not met by the [Context Source Registration]{.HTML_Keyboard}, then an error of type *BadRequestData* shall be raised. -- If a *contextSourceInfo* array is defined and the restrictions expressed by [clause 4.3.6.6](9-tabcontext-information-management-framework.md#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source) are not met by the [Context Source Registration]{.HTML_Keyboard}, then an error of type *BadRequestData* shall be raised. -- If the [Context Source]{.HTML_Keyboard} to be registered has its *mode* property defined as **exclusive**, the following additional restrictions apply: -::: - -::: B2plus -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} already matches against the Entity ID (URI) and any of the Attributes defined in the registration, an error of type *Conflict* shall be raised. -- If an Entity already exists for the supplied Entity ID (URI) and the existing Entity contains any of the Attributes defined in the registration, an error of type *Conflict* shall be raised. -::: - -::: B1plus -- If the [Context Source]{.HTML_Keyboard} to be registered has its *mode* property defined as **redirect**, the following additional restriction applies: -::: - -::: B2plus -- If an existing Entity already matches the [Context Source Registration]{.HTML_Keyboard}, an error of type *Conflict* shall be raised. -::: - -::: B1plus -- If the [Context Source]{.HTML_Keyboard} to be registered has its *mode* property defined as **auxiliary**, the following additional restriction applies: -::: - -::: B2plus -- If the *operations* property is not defined as one of: ["retrieveOps"]{.HTML_Code}, ["retrieveEntity"]{.HTML_Code} or ["queryEntity",]{.HTML_Code} or a combination thereof, an error of type *BadRequestData* shall be raised. -::: - -::: B1plus -- If the property *expiresAt* is not defined then the [Context Source Registration]{.HTML_Keyboard} shall last forever (or until it is deleted from the system). -- If *expiresAt* is a date and time in the past, an error of type *BadRequestData* shall be raised. -- If *expiresAt* is a date and time in the future, implementations shall delete the Registration when this point in time is reached. -- If the NGSI-LD endpoint knows about this [Context Source Registration, ]{.HTML_Keyboard}as there is an existing [Context Source Registration ]{.HTML_Keyboard}whose id (URI) is equivalent, an error of type *AlreadyExists* shall be raised. -- If the subscription document does not include a [Context Source Registration]{.HTML_Keyboard} identifier, a new identifier (URI) shall be automatically generated by the implementation. -- Implementations shall add the concerned [Context Source Registration]{.HTML_Keyboard} and return an 'ok' response together with a registration identifier (*id*). -- This *id* shall be used if NGSI-LD clients need to manage the registration later. -::: - -#### 5.9.2.5 Output data {#taboutput-data-36 number="10.9.2.5"} - -A URI identifying the newly created ContextSourceRegistration. - -### 5.9.3 Update Context Source Registration {#tabupdate-context-source-registration number="10.9.3"} - -#### 5.9.3.1 Description {#tabdescription-37 number="10.9.3.1"} - -This operation allows updating a [Context Source Registration]{.HTML_Keyboard} in an NGSI-LD system. - -#### 5.9.3.2 Use case diagram {#tabuse-case-diagram-37 number="10.9.3.2"} - -A *Context Provider* can update a [Context Source Registration]{.HTML_Keyboard} in an NGSI-LD system as shown in [Figure 5.9.3.2‑1](10-tabapi-operation-definition.md#Figure_5.9.3.2-1). - -::: FL -![](./media/image53.png){style="width:3.47222in;height:2.93056in"} -::: - -::: {#Figure_5.9.3.2-1 .TF} -Figure 5.9.3.2-1: Update context source registration use case -::: - -#### 5.9.3.3 Input data {#tabinput-data-37 number="10.9.3.3"} - -::: B1plus -- [Context Source Registration]{.HTML_Keyboard} identifier (URI), the target [Context Source Registration]{.HTML_Keyboard}. -- A JSON-LD document representing a [Context Source Registration]{.HTML_Keyboard} Fragment [(clause 5.4](10-tabapi-operation-definition.md#tabngsi-ld-fragments)). -::: - -#### 5.9.3.4 Behaviour {#tabbehaviour-37 number="10.9.3.4"} - -::: B1plus -- If the target [Context Source Registration]{.HTML_Keyboard} id (*id*) is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If a "contextSourceInfo" array is defined and the restrictions expressed by [clause 4.3.6.6](9-tabcontext-information-management-framework.md#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source) are not met by the [Context Source Registration]{.HTML_Keyboard}, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD System does not know about the target [Context Source Registration]{.HTML_Keyboard}, because there is no existing [Context Source Registration]{.HTML_Keyboard} whose id (URI) is equivalent, an error of type *ResourceNotFound* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If the data types and restrictions expressed by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration) are not met by the [Context Source Registration]{.HTML_Keyboard} *Fragment*, then an error of type *BadRequestData* shall be raised. -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- If the [Context Source Registration]{.HTML_Keyboard} to be updated has its *mode* property defined as **exclusive**, the following additional restrictions apply: -::: - -::: B2plus -- If an **exclusive** or **redirect** [Context Source Registration]{.HTML_Keyboard} already matches against the Entity ID (URI) and any of the Attributes defined in the registration, an error of type *Conflict* shall be raised. -- If an Entity already exists for the supplied Entity ID (URI) and the existing Entity contains any of the Attributes defined in the registration, an error of type *Conflict* shall be raised. -::: - -::: B1plus -- If the [Context Source Registration]{.HTML_Keyboard} to be updated has its *mode* property defined as **redirect**, the following additional restriction applies: -::: - -::: B2plus -- If an existing Entity already matches the [Context Source Registration]{.HTML_Keyboard}, an error of type *Conflict* shall be raised. -::: - -::: B1plus -- If the [Context Source]{.HTML_Keyboard} to be updated has its *mode* property defined as **auxiliary**, the following additional restriction applies: -::: - -::: B2plus -- If the [operations]{.HTML_Code} property is not defined as one of: ["retrieveOps"]{.HTML_Code}, ["retrieveEntity"]{.HTML_Code} or ["queryEntity"]{.HTML_Code}, an error of type *BadRequestData* shall be raised. -::: - -::: B1plus -- Then, implementations shall modify the target [Context Source Registration]{.HTML_Keyboard} as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour). -::: - -#### 5.9.3.5 Output data {#taboutput-data-37 number="10.9.3.5"} - -None. - -### 5.9.4 Delete Context Source Registration {#tabdelete-context-source-registration number="10.9.4"} - -#### 5.9.4.1 Description {#tabdescription-38 number="10.9.4.1"} - -This operation allows deleting a [Context Source Registration]{.HTML_Keyboard} from an NGSI-LD system. - -#### 5.9.4.2 Use case diagram {#tabuse-case-diagram-38 number="10.9.4.2"} - -A context provider can delete a context source registration from an NGSI-LD system as shown in [Figure 5.9.4.2‑1](10-tabapi-operation-definition.md#Figure_5.9.4.2-1). - -::: FL -![](./media/image54.png){style="width:3.47222in;height:2.83333in"} -::: - -::: {#Figure_5.9.4.2-1 .TF} -Figure 5.9.4.2-1: Delete context source registration use case -::: - -#### 5.9.4.3 Input data {#tabinput-data-38 number="10.9.4.3"} - -Registration identifier (URI) of the context source registration to be deleted (target registration). - -#### 5.9.4.4 Behaviour {#tabbehaviour-38 number="10.9.4.4"} - -::: B1plus -- If the target context source registration id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target context source registration, because there is no existing context source registration whose id (URI) is equivalent, then an error of type *ResourceNotFound* shall be raised. -- Otherwise the context source registration shall be removed. -::: - -#### 5.9.4.5 Output data {#taboutput-data-38 number="10.9.4.5"} - -None. - -## 5.10 Context Source Discovery {#tabcontext-source-discovery number="10.10"} - -### 5.10.1 Retrieve Context Source Registration {#tabretrieve-context-source-registration number="10.10.1"} - -#### 5.10.1.1 Description {#tabdescription-39 number="10.10.1.1"} - -This operation allows retrieving a specific context source registration from an NGSI-LD system. - -#### 5.10.1.2 Use case diagram {#tabuse-case-diagram-39 number="10.10.1.2"} - -A context consumer or a context provider can retrieve a specific context source registration from an NGSI-LD system as shown in [Figure 5.10.1.2‑1](10-tabapi-operation-definition.md#Figure_5.10.1.2-1). - -::: FL -![](./media/image55.png){style="width:3.47222in;height:3.04167in"} -::: - -::: {#Figure_5.10.1.2-1 .TF} -Figure 5.10.1.2-1: Retrieve context source registration use case -::: - -#### 5.10.1.3 Input data {#tabinput-data-39 number="10.10.1.3"} - -Context source registration identifier (id) of the context source registration to be retrieved (target registration). - -#### 5.10.1.4 Behaviour {#tabbehaviour-39 number="10.10.1.4"} - -::: B1plus -- If the context source registration id (*id*) is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about the target context source registration, because there is no existing context source registration whose id (URI) is equivalent, then an error of type *ResourceNotFound* shall be raised. -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- Otherwise return a JSON-LD object representing the [Context Source Registration]{.HTML_Keyboard} as mandated by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration). -::: - -#### 5.10.1.5 Output data {#taboutput-data-39 number="10.10.1.5"} - -A JSON-LD object representing the target context source registration as mandated by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration). - -### 5.10.2 Query Context Source Registrations {#tabquery-context-source-registrations number="10.10.2"} - -#### 5.10.2.1 Description {#tabdescription-40 number="10.10.2.1"} - -This operation allows discovering context source registrations from an NGSI-LD system. The behaviour of the discovery of context source registrations differs significantly from the querying of entities as described in [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities). The approach is that the client submits a query for entities as described in [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities), but instead of receiving the Entity information, it receives a list of [Context Source Registrations]{.HTML_Keyboard} describing [Context Sources]{.HTML_Keyboard} that possibly have some of the requested Entity information. This means that the requested Entities and Attributes are matched against the 'information' property as described in [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations). - -If no temporal query is present, only [Context Source Registrations]{.HTML_Keyboard} for [Context Sources]{.HTML_Keyboard} providing latest information, i.e. without specified time intervals, are considered. If a temporal query is present only [Context Source Registrations]{.HTML_Keyboard} with matching time intervals, i.e. *observationInterval* or *managementInterval,* are considered. - -#### 5.10.2.2 Use case diagram {#tabuse-case-diagram-40 number="10.10.2.2"} - -A *Context Consumer* can discover context source registrations that may be able to provide (part of) the context information specified in the query from an NGSI-LD system as shown in [Figure 5.10.2.2‑1](10-tabapi-operation-definition.md#Figure_5.10.2.2-1). - -::: FL -![](./media/image56.png){style="width:3.48611in;height:3.05556in"} -::: - -::: {#Figure_5.10.2.2-1 .TF} -Figure 5.10.2.2-1: Discover context source registrations use case -::: - -#### 5.10.2.3 Input data {#tabinput-data-40 number="10.10.2.3"} - -::: B1plus -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). Both type name (short hand string) and fully qualified type name (URI) are allowed (optional). -- A list (one or more) of Entity identifiers (optional). -- A list (one or more) of Attribute names (called query projection attributes) (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values, used here to identify relevant attributes) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships, used here to identify relevant GeoProperties and for geographical scoping) as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- In the case of GeoJSON representation: -::: - -::: B2plus -- The name of the *GeoProperty* attribute to use as the geometry for the GeoJSON representation as mandated by [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) (optional). -- A *datasetId* specifying which instance of the value is to be selected if the *GeoProperty* value has multiple instances as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -::: - -::: B1plus -- An NGSI-LD temporal query as per [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language) (optional). -- An NGSI-LD context source query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- A NGSI-LD Scope query as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- A limit to the number of [Context Source Registrations]{.HTML_Keyboard} to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -- A specified language filter as per [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -::: - -It is not possible to retrieve a set of context source registrations related to entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via lists of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. - -#### 5.10.2.4 Behaviour {#tabbehaviour-40 number="10.10.2.4"} - -::: B1plus -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names; -::: - -::: B2 -c) NGSI-LD Query; -::: - -::: B2 -d) NGSI-LD GeoQuery. -::: - -::: B1 -If none of them is provided, then an error of type *BadRequestData* shall be raised (too wide query). Attributes specified in NGSI-LD Query or NGSI-LD GeoQuery shall be used for matching RegistrationInfo elements in the same way as the attributes in the *list of Attribute names*. -::: - -::: B1plus -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or temporal query are not syntactically valid (as per clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language), [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) and [4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)) an error of type *BadRequestData* shall be raised. -- Term to URI expansion of type and Attribute names shall be performed, as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- Otherwise, implementations shall run a query that shall return context source registrations that meet **all** the applicable conditions: -::: - -::: B2plus -- If present, the entity specification in the query consisting of a combination of entity type selector and entity id/entity id pattern (optional) matches an *EntityInfo* specified in a *RegistrationInfo* of the information property in a context source registration. If there is no *EntityInfo* specified in the *RegistrationInfo*, the entity specification is considered matching. This matching is further described in [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations). -- If present, at least one Attribute name specified in the query matches one Property or Relationship in the *RegistrationInfo* element of the information property in a context source registration. If no Properties or Relationships are specified in the *RegistrationInfo*, the Attribute names are considered matching. This matching is further described in [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations). -- If present, the geoquery is matched against the *GeoProperty* identified in the geoquery. If no *GeoProperty* is specified in the geoquery, the default property is *location*. The geoquery matches the *GeoProperty* specified in the [Context Source Registration]{.HTML_Keyboard}, if the location directly matches or if the location possibly contains locations that would match the geoquery. -- If no temporal query is present, only [Context Source Registrations]{.HTML_Keyboard} for [Context Sources]{.HTML_Keyboard} providing latest information, i.e. without specified time intervals, are considered. -- If a temporal query is present, only [Context Source Registrations]{.HTML_Keyboard} with specified time intervals, i.e. *observationInterval* or *managementInterval* are considered. If the *timeproperty* is *observedAt* or no *timeproperty* is specified in the temporal query (default: *observedAt*), the temporal query is matched against the *observationInterval* (if present). If the *timeproperty* is *createdAt*, *modifiedAt* or *deletedAt*, the temporal query is matched against the *managementInterval* (if present). If the relevant interval is not present, there is no match: -::: - -::: B3plus -- The semantics of the match is that the *timeAt* in the case of the ["before"]{.HTML_Code} and ["after"]{.HTML_Code} relation is contained in or is an endpoint of a time period included in the specified time interval. In the case of the ["between"]{.HTML_Code} relation there is a match if there is an overlap between the interval specified by the *timeAt* and *endTimeAt* and the specified time interval. -::: - -::: B2plus -- If present, the conditions specified by the context source query filter match the respective [Context Source]{.HTML_Keyboard} Properties (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)). -- If present, the Scope query (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)) is matched against the *scope* property. -::: - -::: B1plus -- Pagination logic shall be in place as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -::: - -#### 5.10.2.5 Output data {#taboutput-data-40 number="10.10.2.5"} - -A JSON-LD array of matching [Context Source Registrations]{.HTML_Keyboard} as defined by [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration). Instead of the original [Context Source Registration]{.HTML_Keyboard} which may contain a lot of irrelevant information, implementations should return filtered [Context Source Registrations]{.HTML_Keyboard}, which only contain context source registration information relevant for the query, in particular only matching *RegistrationInfo* elements. - -## 5.11 Context Source Registration Subscription {#tabcontext-source-registration-subscription number="10.11"} - -### 5.11.1 Introduction {#tabintroduction-19 number="10.11.1"} - -[Context Source Registration]{.HTML_Keyboard} Subscriptions in general work like context information subscriptions; however, instead of resulting in notifications with context information, the notifications contain [Context Source Registrations]{.HTML_Keyboard} describing [Context Sources]{.HTML_Keyboard} that can potentially provide the requested context information. If no temporal query is present, only [Context Source Registrations]{.HTML_Keyboard} for [Context Sources]{.HTML_Keyboard} providing latest information, i.e. without such time intervals, are considered. If a temporal query is present only [Context Source Registrations]{.HTML_Keyboard} with matching time intervals, i.e. *observationInterval* or *managementInterval*, are considered. - -### 5.11.2 Create Context Source Registration Subscription {#tabcreate-context-source-registration-subscription number="10.11.2"} - -#### 5.11.2.1 Description {#tabdescription-41 number="10.11.2.1"} - -This operation allows creating a new [Context Source Registration]{.HTML_Keyboard} Subscription. - -#### 5.11.2.2 Use case diagram {#tabuse-case-diagram-41 number="10.11.2.2"} - -A [Context Source]{.HTML_Keyboard} *Subscriber* can subscribe to a new [Context Source Registration]{.HTML_Keyboard} as shown in [Figure 5.11.2.2‑1](10-tabapi-operation-definition.md#Figure_5.11.2.2-1). - -::: FL -![](./media/image57.png){style="width:3.5in;height:2.84722in"} -::: - -::: {#Figure_5.11.2.2-1 .TF} -Figure 5.11.2.2-1: Subscribe Context Source Registration use case -::: - -#### 5.11.2.3 Input data {#tabinput-data-41 number="10.11.2.3"} - -::: B1plus -- A data structure (represented in JSON-LD) conforming to the Subscription data type as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). -::: - -#### 5.11.2.4 Behaviour {#tabbehaviour-41 number="10.11.2.4"} - -::: B1plus -- The behaviour shall be as described in [clause 5.8.1.4](10-tabapi-operation-definition.md#tabbehaviour-31), restricted to the local case (where Subscriptions cannot be received from remote Brokers), with the following exceptions: -::: - -::: B2plus -- If all checks described in [clause 5.8.1.4](10-tabapi-operation-definition.md#tabbehaviour-31) pass, implementations shall add a new [Context Source Registration]{.HTML_Keyboard} Subscription. The parameters of the created subscription shall be configured as described in [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). -- Instead of directly matching the entities and watched Attributes from the Subscription with the [Context Source]{.HTML_Keyboard} registrations, the entities specified in the subscription, the watched Attributes and the Attributes specified in the notification parameter are matched against the respective *information* property of the [Context Source]{.HTML_Keyboard} registrations. If either the watched Attributes or the Attributes in the notification are not present or of length 0, all possible Attributes (if present in the [Context Source Registrations]{.HTML_Keyboard}) for matching entities match. This matching is further described in [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations). -- If present, the geoquery in the geoQ element is matched against the *GeoProperty* of the subscription identified in the geoQ element. If no *GeoProperty* is specified in the geoquery, the default property is 'location'. The geoquery matches the *GeoProperty* specified in the [Context Source Registration]{.HTML_Keyboard}, if the location directly matches or if the location possibly contains locations that would match the geoquery. -- If no temporal query is present in the *temporalQ* element, only [Context Source Registrations]{.HTML_Keyboard} for [Context Sources]{.HTML_Keyboard} providing latest information, i.e. without specified time intervals for *observationInterval* or *managementInterval*, are considered. -- If a temporal query in the *temporalQ* element is present, only [Context Source Registrations]{.HTML_Keyboard} with specified time intervals are considered. If the *timeproperty* is ["observedAt"]{.HTML_Code} or no *timeproperty* is specified in the temporal query (default: *observedAt*), the temporal query is matched against the *observationInterval* (if present). If the *timeproperty* is ["createdAt"]{.HTML_Code}, ["modifiedAt"or "deletedAt",]{.HTML_Code} the temporal query is matched against the *managementInterval* (if present). If the relevant interval is not present, there is no match: -::: - -::: B3plus -- The semantics of the match is that the *timeAt* in the case of the ["before"]{.HTML_Code} and ["after"]{.HTML_Code} relation is contained in or is an endpoint of a time period included in the specified time interval. In the case of the ["between"]{.HTML_Code} relation there is a match if there is an overlap between the interval specified by the *timeAt* and *endTimeAt* and the specified time interval. -::: - -::: B2plus -- If present, the conditions specified by the context source filter match the respective [Context Source]{.HTML_Keyboard} Properties (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)). -::: - -::: B1plus -- If the subscription defines a *timeInterval* term, a *CsourceNotification* [(clause 5.3.2](10-tabapi-operation-definition.md#tabcsourcenotification)) with all matching [Context Source Registrations]{.HTML_Keyboard} shall be sent periodically, initially on subscription and when the time interval (in seconds) specified in such value field is reached, independent of any changes to the set of [Context Source]{.HTML_Keyboard} registrations. -- If *timeInterval* is not defined, initially on subscription and whenever there is a change of a matching [Context Source Registration]{.HTML_Keyboard} (creation, update, deletion), implementations shall post a new *CsourceNotification* to the endpoint specified in the notification parameters informing about this change by providing the [Context Source Registration]{.HTML_Keyboard}(s) together with the appropriate trigger reason in the *triggerReason* member. -- If present, the conditions specified by the context source query match the respective [Context Source]{.HTML_Keyboard} Properties (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)). -- If present, the Scope query (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)) is matched against the *scope* property. -::: - -#### 5.11.2.5 Output data {#taboutput-data-41 number="10.11.2.5"} - -A URI identifying the newly created Subscription. - -### 5.11.3 Update Context Source Registration Subscription {#tabupdate-context-source-registration-subscription number="10.11.3"} - -#### 5.11.3.1 Description {#tabdescription-42 number="10.11.3.1"} - -This operation allows updating an existing [Context Source Registration]{.HTML_Keyboard} Subscription. - -#### 5.11.3.2 Use case diagram {#tabuse-case-diagram-42 number="10.11.3.2"} - -A context source subscriber can update a [Context Source Registration]{.HTML_Keyboard} Subscription as shown in [Figure 5.11.3.2‑1](10-tabapi-operation-definition.md#Figure_5.11.3.2-1). - -::: FL -![](./media/image58.png){style="width:3.5in;height:2.93056in"} -::: - -::: {#Figure_5.11.3.2-1 .TF} -Figure 5.11.3.2-1: Update Context Source Registration Subscription use case -::: - -#### 5.11.3.3 Input data {#tabinput-data-42 number="10.11.3.3"} - -::: B1plus -- Subscription identifier (URI), the target [Context Source Registration]{.HTML_Keyboard} Subscription. -- A JSON-LD document representing a Subscription Fragment. -::: - -#### 5.11.3.4 Behaviour {#tabbehaviour-42 number="10.11.3.4"} - -::: B1plus -- If the Subscription Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the data types and restrictions expressed by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription) are not met by the Subscription Fragment, then an error of type *BadRequestData* shall be raised. -- Then, implementations shall modify the target subscription as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour). -- Finally, send a notification with all currently matching [Context Source Registrations]{.HTML_Keyboard}. -::: - -#### 5.11.3.5 Output data {#taboutput-data-42 number="10.11.3.5"} - -None. - -### 5.11.4 Retrieve Context Source Registration Subscription {#tabretrieve-context-source-registration-subscription number="10.11.4"} - -#### 5.11.4.1 Description {#tabdescription-43 number="10.11.4.1"} - -This operation allows retrieving an existing [Context Source Registration]{.HTML_Keyboard} Subscription. - -#### 5.11.4.2 Use case diagram {#tabuse-case-diagram-43 number="10.11.4.2"} - -A [Context Source]{.HTML_Keyboard} subscriber can retrieve a specific [Context Source Registration]{.HTML_Keyboard} Subscription as shown in Figure 5.11.4.2-1. - -::: FL -![](./media/image59.png){style="width:3.54167in;height:3.04167in"} -::: - -::: {#Figure_5.11.4.2-1 .TF} -Figure 5.11.4.2-1: Retrieve Context Source Registration Subscription use case -::: - -#### 5.11.4.3 Input data {#tabinput-data-43 number="10.11.4.3"} - -Id (URI) of the subscription to be retrieved (target subscription). - -#### 5.11.4.4 Behaviour {#tabbehaviour-43 number="10.11.4.4"} - -::: B1plus -- If the subscription Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the identifier provided does not correspond to any existing subscription in the system then an error of type *ResourceNotFound* shall be raised. -- Otherwise implementations shall query the [Context Source Registration]{.HTML_Keyboard} Subscriptions and obtain the subscription data to be returned to the caller. -::: - -#### 5.11.4.5 Output data {#taboutput-data-43 number="10.11.4.5"} - -A JSON-LD object representing the subscription details as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). - -### 5.11.5 Query Context Source Registration Subscriptions {#tabquery-context-source-registration-subscriptions number="10.11.5"} - -#### 5.11.5.1 Description {#tabdescription-44 number="10.11.5.1"} - -This operation allows querying existing [Context Source Registration]{.HTML_Keyboard} Subscriptions. - -#### 5.11.5.2 Use case diagram {#tabuse-case-diagram-44 number="10.11.5.2"} - -A context source subscriber can query all existing [Context Source Registration]{.HTML_Keyboard} Subscriptions as shown in Figure 5.11.5.2-1. - -::: FL -![](./media/image60.png){style="width:3.65278in;height:3.06944in"} -::: - -::: {#Figure_5.11.5.2-1 .TF} -Figure 5.11.5.2-1: Query Context Source Registration Subscriptions use case -::: - -#### 5.11.5.3 Input data {#tabinput-data-44 number="10.11.5.3"} - -A limit to the number of [Context Source Registration]{.HTML_Keyboard} Subscriptions to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). - -#### 5.11.5.4 Behaviour {#tabbehaviour-44 number="10.11.5.4"} - -::: B1plus -- The NGSI-LD System shall list all the existing [Context Source Registration]{.HTML_Keyboard} Subscriptions. -- Pagination logic shall be in place as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). -::: - -#### 5.11.5.5 Output data {#taboutput-data-44 number="10.11.5.5"} - -A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by [clause 5.2.12](10-tabapi-operation-definition.md#tabsubscription). - -### 5.11.6 Delete Context Source Registration Subscription {#tabdelete-context-source-registration-subscription number="10.11.6"} - -#### 5.11.6.1 Description {#tabdescription-45 number="10.11.6.1"} - -This operation allows deleting an existing [Context Source Registration]{.HTML_Keyboard} Subscription. - -#### 5.11.6.2 Use case diagram {#tabuse-case-diagram-45 number="10.11.6.2"} - -A context source subscriber can delete a [Context Source Registration]{.HTML_Keyboard} Subscription as shown in [Figure 5.11.6.2‑1](10-tabapi-operation-definition.md#Figure_5.11.6.2-1). - -::: FL -![](./media/image61.png){style="width:3.63889in;height:2.83333in"} -::: - -::: {#Figure_5.11.6.2-1 .TF} -Figure 5.11.6.2-1: Delete Context Source Registration Subscriptions use case -::: - -#### 5.11.6.3 Input data {#tabinput-data-45 number="10.11.6.3"} - -::: B1plus -- A subscription identifier (URI). -::: - -#### 5.11.6.4 Behaviour {#tabbehaviour-45 number="10.11.6.4"} - -::: B1plus -- If the subscription Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the subscription id provided does not correspond to any existing subscription in the system then an error of type *ResourceNotFound* shall be raised. -- Otherwise implementations shall delete the [Context Source Registration]{.HTML_Keyboard} Subscription and no longer perform notifications concerning that Subscription. -::: - -#### 5.11.6.5 Output data {#taboutput-data-45 number="10.11.6.5"} - -None. - -### 5.11.7 Notification behaviour {#tabnotification-behaviour-1 number="10.11.7"} - -A [Context Source]{.HTML_Keyboard} Notification is a message that allows a subscriber to be aware of the changes in the set of [Context Source Registrations]{.HTML_Keyboard} describing [Context Sources]{.HTML_Keyboard} that can potentially provide the requested context information. Implementations shall exhibit the behaviour described in [clause 5.8.6](10-tabapi-operation-definition.md#tabnotification-behaviour) with the following exceptions: - -::: B1plus -- If a subscription defines a *timeInterval* member, a *CsourceNotification* [(clause 5.3.2](10-tabapi-operation-definition.md#tabcsourcenotification)) shall be sent on initial subscription and periodically, when the time specified time interval (in seconds) has elapsed, regardless of any changes to the set of context source registrations. The *CsourceNotification* message shall include all the [Context Source Registrations]{.HTML_Keyboard} whose *information* property matches the entities and watched Attributes or Attributes specified in the notification parameter and, if present, have a matching geoquery. If either the watched Attributes or the Attributes in the notification are not present or of length 0, all possible Attributes (if present in the [Context Source Registrations]{.HTML_Keyboard}) for fitting entities match. -- If a subscription does not define a *timeInterval* term, the csource notification shall be sent on initial subscription and whenever there is a change in a matching csource registration. Such a change may be triggered by the creation of a new matching csource registration, the update of a csource registration (whether matching before the update, after the update or in both cases) or the deletion of a matching csource registration. The notification message shall include the matching csource registration(s) together with the appropriate trigger reason in the *triggerReason* member. -- Instead of providing the original [Context Source Registration]{.HTML_Keyboard} which may contain a lot of irrelevant information, implementations should return filtered [Context Source Registrations]{.HTML_Keyboard}, which only contain context source registration information relevant for the subscription, in particular only matching *RegistrationInfo* elements. -- A csource notification shall be sent as follows: -::: - -::: B2plus -- The structure of the csource notification message shall be as mandated by [clause 5.3.2](10-tabapi-operation-definition.md#tabcsourcenotification). -- [A csource notification shall be sent to the ]{.ondemand_CHAR_color_000000}*endpoint*[.]{.ondemand_CHAR_color_000000} -- The *notification.timesSent* member shall be incremented by one. -- The *notification.lastNotification* member shall be updated with the current timestamp. -- If the notification is sent successfully: -::: - -::: B3plus -- Update *notification.lastSuccess* with the current timestamp. -::: - -::: B2plus -- [If the notification is not sent successfully:]{.ondemand_CHAR_color_000000} -::: - -::: B3plus -- Update *notification.lastFailure* with the current timestamp. -- Update the subscription *status* to ["failed"]{.HTML_Code}. -::: - -## 5.12 Matching Context Source Registrations {#tabmatching-context-source-registrations number="10.12"} - -When querying [Context Source Registrations]{.HTML_Keyboard} as described in [clause 5.10.2](10-tabapi-operation-definition.md#tabquery-context-source-registrations) and subscribing to [Context Source Registrations]{.HTML_Keyboard} as described in [clause 5.11.2](10-tabapi-operation-definition.md#tabcreate-context-source-registration-subscription), the Entities and/or Attributes specified in the request have to be matched against the set of [Context Source Registrations]{.HTML_Keyboard}, extracting the matching ones. This clause describes this matching. - -The relevant specification information in the query for [Context Source Registrations]{.HTML_Keyboard} are the selector of Entity Types (if present), the list of Entity identifiers (if present), the id pattern (if present) and the list of Attribute names (if present). In the case of subscriptions to [Context Source Registrations]{.HTML_Keyboard}, it is the Entities as specified in the array of type *EntitySelector* in the Subscription, the *watchedAttributes* element of the *Subscription* and the attributes specified as part of the *NotificationParams* element of the Subscription. If the attributes in the *NotificationParams* element are empty or not present, the matching is done as if no attribute identifiers have been specified, otherwise the combination of the *watchedAttributes* and the attributes in the *NotificationParams* element are used as the specified attribute identifiers for the matching. - -Even though the way relevant Entities are specified differs in queries and subscriptions, they consist of the same information, so for the purpose of this clause, the specification of Entity Types or Attributes refers to the relevant elements for matching, i.e. Entity Types, Entity identifiers, id pattern and Attribute names. A specification of Entity Types or Attributes shall contain at least one of: - -::: BL -a. selector of Entity Types; or -b. list of Attribute names. -::: - -A specification of Entity Types or Attributes matches a [Context Source Registration]{.HTML_Keyboard} if at least one of the *RegistrationInfo* elements in the *information* element matches. An Entity specification matches a *RegistrationInfo* if the following conditions hold: - -::: B1plus -- If present, the selector of Entity Types, Entity identifiers and id pattern match at least one of the *EntityInfo* elements of the *RegistrationInfo* (see below). -- If present, the Attribute identifiers match the combination of Properties and Relationships specified in the *RegistrationInfo* (see below). -::: - -An Entity specification consisting of selector of Entity Types, Entity identifiers and id pattern matches an *EntityInfo* element of the *RegistrationInfo* if the type selector matches the entity types in the *EntityInfo* element and one of the following conditions holds: - -::: B1plus -- The *EntityInfo* contains neither an *id* nor an *idPattern*. -- One of the specified Entity identifiers matches the *id* in the *EntityInfo*. -- At least one of the specified Entity identifiers matches the *idPattern* in the *EntityInfo*. -- The specified id pattern matches the *id* in the *EntityInfo*. -- Both a specified id pattern and an *idPattern* in the *Entity Info* are present (since in the general case it is not easily feasible to determine if there can be identifiers matching both patterns). -::: - -Attribute names match the combination of Properties and Relationships if one of the following conditions hold: - -::: B1plus -- No Attribute names have been specified (as this means all Attributes are requested). -- The combination of Properties and Relationships is empty (as this means only Entities have been registered and the [Context Sources]{.HTML_Keyboard} may have matching Property or Relationship instances). -- If at least one of the specified attribute names matches a Property or Relationship specified in the *RegistrationInfo*. -::: - -If the request that triggered the matching includes a *datasetId* parameter and the CSourceRegistration to be matched contains a *datasetId* element, the CSourceRegistration should only be considered matching, if both have at least one value in common. If only one of them specifies a *datasetId*, it is considered a match. - -In the case of distributed operations (see [clause 4.3.6.4](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations)), where a listing of all previously encountered [Context Sources ]{.HTML_Keyboard}is supplied with the request, no registration shall match if the CSourceRegistration *contextSourceAlias* can be found within the listing of previously encountered [Context Sources.]{.HTML_Keyboard} - -Note that distributed queries (see [clause 4.3.6.7](9-tabcontext-information-management-framework.md#tabquerying-and-retrieving-distributed-entities-as-unitary-operations)), can be supplied with an EntityMap (see [clause 4.5.25](9-tabcontext-information-management-framework.md#tabngsi-ld-entitymap-representation)) which lists all Entity ids successfully matched during a previous request. If the location of an EntityMap is passed into a subsequent request, the retrieved EntityMap shall be used in preference to the matching algorithm described above, provided that the EntityMap is valid and has not expired. - -## 5.13 Storing, Managing and Serving \@contexts {#tabstoring-managing-and-serving-contexts number="10.13"} - -### 5.13.1 Introduction {#tabintroduction-20 number="10.13.1"} - -[Context Brokers]{.HTML_Keyboard} optionally (see [clause 4.3.5](9-tabcontext-information-management-framework.md#tabngsi-ld-api-structure-and-implementation-options)) offer the capability to store and serve *\@contexts* to clients. The stored *\@contexts* may be managed by clients directly, via the APIs specified in [clause 5.13](10-tabapi-operation-definition.md#tabstoring-managing-and-serving-contexts). Clients can store custom user *\@contexts* at the Context Broker, effectively using the Context Broker as a *\@context* server. - -Moreover, in order to optimize performance, brokers may automatically store and use the stored copies of common \@contexts as a local cache, downloading them just once, thus avoiding fetching them over and over again at each NGSI-LD request. In order for the broker to understand if a needed *\@context* is already in the local storage or not, the broker uses the URL, where the *\@context* is originally hosted, as an identifier for it in the local storage. Consequently, the broker has no ability to cache *\@contexts* that arrive to it as **embedded** parts within the NGSI-LD documents, since they are not uniquely (and implicitly) identified by any URL; [Context Brokers]{.HTML_Keyboard} only cache *\@contexts* that are referred to by means of explicit URLs (either in the HTTP Link header or as URLs in the payload body). Thus, the **recommended best-practice, in order to exploit caching, is that clients do not embed their user** *\@contexts* **into their NGSI-LD documents**; instead clients should explicitly host their user *\@contexts* at their premises, or use the broker's capability to host user *\@contexts* on their behalf. - -When an external *\@context* is stored, either explicitly upon a client's request or implicitly downloaded for caching purposes, the Context Broker generates a unique local *\@context* identifier. The original *\@context's* URL, if any, is stored alongside the generated local id. The local id is then used for subsequent managing operations on the specific *\@context*, that are specified in clauses [5.13.2](10-tabapi-operation-definition.md#tabadd-context) to 5.13.5. Moreover, the broker tags the entry with the current timestamp, (createdAt) so that, subsequently, clients can check the timestamp before deciding whether to force a refresh of the stored copy of the *\@context*. This is primarily intended as a means for clients to well-behave, thus avoiding triggering continuous refresh of a stored *\@context* on the broker, for fear that it is not at the latest version. - -Stored *\@contexts* are flagged as one of three kinds: ["Cached"]{.HTML_Code}, ["Hosted"]{.HTML_Code}, ["ImplicitlyCreated"]{.HTML_Code}: - -::: B1plus -- **Cached:** *\@contexts* implicitly and automatically fetched by the broker from external URLs during normal NGSI-LD operations are flagged as ["Cached"]{.HTML_Code}. A locally unique identifier is generated for each *\@context* not already in the internal storage. The downloaded content, its URL and the current time in UTC are stored alongside the locally unique identifier. Implementations shall periodically invalidate the "Cached" *\@contexts*. Depending on the binding of the NGSI-LD API to a specific protocol, that specific protocol may provide explicit indications about expiration times of cached content. In such cases, implementations shall comply with the indications provided by the protocol. Implementations should assign a heuristic expiration time when an explicit time is not specified. **Entries flagged as "Cached" shall not be served by brokers on-demand, but only be used as a local cache to improve performance**. -- **Hosted:** *\@contexts* that are explicitly added by users are flagged as ["Hosted"]{.HTML_Code}. These entries shall be served by brokers on-demand. -- **ImplicitlyCreated:** *\@contexts* that are implicitly, but *ex-novo*, created by the broker as a result of a user request are flagged as ["ImplicitlyCreated"]{.HTML_Code}. For instance, when a client creates a subscription using an *\@context* that is an array, and the broker has to notify with Content-Type ["application/json"]{.HTML_Code}, then the broker needs this *\@context* array to be hosted at a URL. Hence the broker has to create a new *\@context* that is an array, and it is going to be served from an own URL. These entries shall be served by brokers on-demand. -::: - -### 5.13.2 Add \@context {#tabadd-context number="10.13.2"} - -#### 5.13.2.1 Description {#tabdescription-46 number="10.13.2.1"} - -With this operation, a client can ask the broker to store the full content of a specific *\@context*, by giving it to the broker. - -#### 5.13.2.2 Use case diagram {#tabuse-case-diagram-46 number="10.13.2.2"} - -A client can add an *\@context* to be stored within an NGSI-LD system as shown in [Figure 5.13.2.2‑1](10-tabapi-operation-definition.md#Figure_5.13.2.2-1). - -::: FL -![](./media/image62.png){style="width:3.47222in;height:2.90278in"} -::: - -::: {#Figure_5.13.2.2-1 .TF} -Figure 5.13.2.2-1: Add \@context use case -::: - -#### 5.13.2.3 Input data {#tabinput-data-46 number="10.13.2.3"} - -A JSON object that has a top-level field named *\@context*, i.e. a JSON object representing a JSON-LD "local context". As specified in the JSON-LD specification [[2]](7-tabreferences.md#2), all extra information located outside of the *\@context* subtree in the referenced object shall be discarded. - -#### 5.13.2.4 Behaviour {#tabbehaviour-46 number="10.13.2.4"} - -A new entry is created in the local storage and a locally unique identifier (URI) is generated for it. The JSON object representing the client-supplied *\@context* and the current UTC time are stored alongside the locally unique identifier. That identifier shall be given back as a result in the output data. The entry is flagged as being of kind ["Hosted"]{.HTML_Code}. - -The behaviour described in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) about JSON and JSON-LD validation shall be applied in case of invalid *\@context*. - -#### 5.13.2.5 Output data {#taboutput-data-46 number="10.13.2.5"} - -A locally unique URI identifying the *\@context* in the broker's internal storage. - -### 5.13.3 List \@contexts {#tablist-contexts number="10.13.3"} - -#### 5.13.3.1 Description {#tabdescription-47 number="10.13.3.1"} - -With this operation a client can obtain a list of URLs that represent all of the *\@contexts* stored in the local context store of the broker. Each URL can be used to download the corresponding *\@context*, and, in case the *\@context's* kind is ["Cached"]{.HTML_Code}, it shall be the original URL the broker downloaded the *\@context* from. - -In case a *details* flag is set to *true*, the client obtains a list of JSON objects, each representing information (metadata) about an *\@context* currently stored by the broker. Each JSON object contains information about the *\@context's* original URL (if any), its local identifier in the broker's storage, its kind (["Cached"]{.HTML_Code}, ["Hosted"]{.HTML_Code} and ["ImplicitlyCreated"]{.HTML_Code}), its creation timestamp, its expiry date, and additional optional information. - -#### 5.13.3.2 Use case diagram {#tabuse-case-diagram-47 number="10.13.3.2"} - -A client can list all *\@contexts* stored within an NGSI-LD system as shown in [Figure 5.13.3.2‑1](10-tabapi-operation-definition.md#Figure_5.13.3.2-1). - -::: FL -![](./media/image63.png){style="width:3.47222in;height:3.13889in"} -::: - -::: {#Figure_5.13.3.2-1 .TF} -Figure 5.13.3.2-1: List \@contexts use case -::: - -#### 5.13.3.3 Input data {#tabinput-data-47 number="10.13.3.3"} - -::: B1plus -- A *kind* filter indicating the kind of stored *\@contexts* that are to be included in the output list. Currently, possible kinds are ["Cached"]{.HTML_Code}, ["Hosted"]{.HTML_Code} and ["ImplicitlyCreated"]{.HTML_Code} (optional). -- A boolean *details* flag indicating that detailed JSON objects representing metadata about the stored *\@contexts* instead of simple URLs are requested (optional). -::: - -#### 5.13.3.4 Behaviour {#tabbehaviour-47 number="10.13.3.4"} - -The broker shall provide a URL or JSON object for each *\@context* currently stored in the internal broker's storage, that match the filter. If no filter is specified, all kinds are included. - -#### 5.13.3.5 Output data {#taboutput-data-47 number="10.13.3.5"} - -A list of URLs, or a list of resulting JSON objects containing the following fields: - -::: B1plus -- URL; -- localId; -- kind; -- createdAt; -- expiresAt [OPTIONAL]; -- lastUsage [OPTIONAL]; -- numberOfHits [OPTIONAL, number of times the \@context was found in the storage]; -- extraInfo [OPTIONAL, used by implementations to report any kind of custom information]. -::: - -### 5.13.4 Serve \@context {#tabserve-context number="10.13.4"} - -#### 5.13.4.1 Description {#tabdescription-48 number="10.13.4.1"} - -With this operation a client can obtain the full content of a specific *\@context* (only for *\@contexts* of kind ["Hosted"]{.HTML_Code} or ["ImplicitlyCreated"]{.HTML_Code}), which is currently stored in the broker's internal storage, or its metadata (for all kinds of stored *\@contexts*). - -#### 5.13.4.2 Use case diagram {#tabuse-case-diagram-48 number="10.13.4.2"} - -A client can request the broker to serve a specific *\@context* stored within the NGSI-LD system as shown in Figure 5.13.4.2-1. - -::: FL -![](./media/image64.png){style="width:3.47222in;height:3.13889in"} -::: - -::: {#Figure_5.13.4.2-1 .TF} -Figure 5.13.4.2-1: Serve \@context use case -::: - -#### 5.13.4.3 Input data {#tabinput-data-48 number="10.13.4.3"} - -::: B1plus -- The locally unique identifier that identifies the desired *\@context* in the broker's internal storage. Such unique identifiers are obtained by the client as a result of either a "Add *\@context*" [(clause 5.13.2](10-tabapi-operation-definition.md#tabadd-context)) API operation or of a "List *\@contexts*" [(clause 5.13.3](10-tabapi-operation-definition.md#tablist-contexts)) API operation. For *\@contexts* of kind ["Cached"]{.HTML_Code} this can also be the original URL the broker downloaded the \@context from. -- A boolean *details* flag indicating that a JSON object representing metadata about the *\@context*, instead of the full content, is requested (optional). -::: - -#### 5.13.4.4 Behaviour {#tabbehaviour-48 number="10.13.4.4"} - -::: B1plus -- If *details* is set to *false*, or *details* is not present, the broker shall give back the full content of the *\@context* that corresponds to the indicated local identifier, serving it from its internal storage, if the *\@context* that corresponds to the indicated local identifier is of kind ["Hosted"]{.HTML_Code} or ["ImplicitlyGenerated"]{.HTML_Code}. It shall give back *OperationNotSupported* error if it is of kind ["Cached"]{.HTML_Code}. It shall give back *ResourceNotFound* if the identifier is not found. -- Otherwise, if *details* is set to *true*, the broker shall give back metadata about the *\@context* that corresponds to the indicated local identifier. It shall give back *ResourceNotFound* error if the identifier is not found. -::: - -#### 5.13.4.5 Output data {#taboutput-data-48 number="10.13.4.5"} - -The full content of the indicated *\@context* (or its metadata as specified in [clause 5.13.3.5](10-tabapi-operation-definition.md#taboutput-data-47)), or *ResourceNotFound/OperationNotSupported* errors. - -### 5.13.5 Delete and Reload \@context {#tabdelete-and-reload-context number="10.13.5"} - -#### 5.13.5.1 Description {#tabdescription-49 number="10.13.5.1"} - -With this operation, a client supplies a local identifier to the broker, indicating a stored *\@context*, that the broker shall remove from its storage. For *\@contexts* of kind ["Cached"]{.HTML_Code} this can also be the original URL the broker downloaded the *\@context* from. If the entry in the local storage that corresponds to the identifier is itself an array of *\@contexts*, this operation will **not** delete the children, i.e. the *\@contexts* in the array, but just the entry. - -#### 5.13.5.2 Use case diagram {#tabuse-case-diagram-49 number="10.13.5.2"} - -A client can request the broker to delete (and optionally reload) a specific *\@context* stored within the NGSI-LD system as shown in [Figure 5.13.5.2‑1](10-tabapi-operation-definition.md#Figure_5.13.5.2-1). - -::: FL -![](./media/image65.png){style="width:3.47222in;height:2.90278in"} -::: - -::: {#Figure_5.13.5.2-1 .TF} -Figure 5.13.5.2-1: Delete and Reload \@context use case -::: - -#### 5.13.5.3 Input data {#tabinput-data-49 number="10.13.5.3"} - -::: B1plus -- The locally unique identifier that identifies the desired *\@context* in the broker's internal storage. For *\@contexts* of kind ["Cached"]{.HTML_Code} this can also be the original URL the broker downloaded the *\@context* from. -- A *reload* boolean flag indicating that reloading of the *\@context* shall be attempted (optional). -::: - -#### 5.13.5.4 Behaviour {#tabbehaviour-49 number="10.13.5.4"} - -::: B1plus -- If the *\@context* identifier is not supplied, then an error of type *BadRequestData* shall be raised. -- If the *\@context* identifier does not correspond to any existing entry in the *\@context* storage, then an error of type *ResourceNotFound* shall be raised. -- If *reload* is *true* and the kind of the *\@context* is ["Cached"]{.HTML_Code}, implementations shall try to re-download the identified *\@context* from its original URL, before removing it from the internal storage. If downloading fails, or the downloaded *\@context* is invalid according to JSON and JSON-LD validation of [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation), then an error of type *LdContextNotAvailable* shall be raised. More detailed information about the errors shall be specified in the *ProblemDetails* (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) field of the response. In case of any error, the operation ends without removing the existing *\@context*. Otherwise, the existing *\@context* is replaced with the newly downloaded one. -- If *reload* is *true* and the kind of the *\@context* is **not** ["Cached",]{.HTML_Code} implementations shall return a *BadRequestData* error. -- If *reload* is *false* (or *reload* is not supplied), implementations shall remove from the internal storage the *\@context* that corresponds to the given identifier. The local identifier is used for finding the *\@contexts* in the internal broker's storage. If the local identifier is not in the storage, a *ResourceNotFound* error shall be raised. -::: - -#### 5.13.5.5 Output data {#taboutput-data-49 number="10.13.5.5"} - -None. - -## 5.14 Context Source Entity Mapping {#tabcontext-source-entity-mapping number="10.14"} - -### 5.14.1 Retrieve EntityMap {#tabretrieve-entitymap number="10.14.1"} - -#### 5.14.1.1 Description {#tabdescription-50 number="10.14.1.1"} - -With this operation a client can obtain a cached EntityMap which is currently stored in the broker's internal storage, or memory. - -#### 5.14.1.2 Use case diagram {#tabuse-case-diagram-50 number="10.14.1.2"} - -A client can request the broker to retrieve a specific EntityMap within the NGSI-LD system as shown in Figure 5.14.1.2-1. - -::: FL -![](./media/image66.png){style="width:3.41667in;height:3.125in"} -::: - -::: {#Figure_5.14.1.2-1 .TF} -Figure 5.14.1.2-1: Retrieve EntityMap -::: - -#### 5.14.1.3 Input data {#tabinput-data-50 number="10.14.1.3"} - -EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). - -#### 5.14.1.4 Behaviour {#tabbehaviour-50 number="10.14.1.4"} - -::: B1plus -- If the Entity ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type *ResourceNotFound* shall be raised. -- Otherwise, return a JSON-LD object representing the EntityMap as mandated by [clause 5.2.39](10-tabapi-operation-definition.md#tabentitymap). -::: - -#### 5.14.1.5 Output data {#taboutput-data-50 number="10.14.1.5"} - -A JSON-LD object representing the target EntityMap as mandated by [clause 5.2.39](10-tabapi-operation-definition.md#tabentitymap). - -### 5.14.2 Update EntityMap {#tabupdate-entitymap number="10.14.2"} - -#### 5.14.2.1 Description {#tabdescription-51 number="10.14.2.1"} - -This operation allows performing a **partial update on an NGSI-LD EntityMap.** A partial update only changes the elements provided in the EntityMap Fragment, leaving the rest as they are. - -#### 5.14.2.2 Use case diagram {#tabuse-case-diagram-51 number="10.14.2.2"} - -A client can request the broker to update an EntityMap which is currently stored in the broker's internal storage as shown in [Figure 5.14.2.2‑1](10-tabapi-operation-definition.md#Figure_5.14.2.2-1). - -::: FL -![](./media/image67.png){style="width:3.41667in;height:2.875in"} -::: - -::: {#Figure_5.14.2.2-1 .TF} -Figure 5.14.2.2-1: Update EntityMap -::: - -#### 5.14.2.3 Input data {#tabinput-data-51 number="10.14.2.3"} - -::: B1plus -- EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). -- A JSON-LD document representing an EntityMap. -::: - -#### 5.14.2.4 Behaviour {#tabbehaviour-51 number="10.14.2.4"} - -::: B1plus -- If the EntityMap ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type *ResourceNotFound* shall be raised. -- Perform an update operation on the target EntityMap using the fields specified within then JSON-LD document. Any provided output-only fields shall be ignored. -::: - -#### 5.14.2.5 Output data {#taboutput-data-51 number="10.14.2.5"} - -None. - -### 5.14.3 Delete EntityMap {#tabdelete-entitymap number="10.14.3"} - -#### 5.14.3.1 Description {#tabdescription-52 number="10.14.3.1"} - -This operation allows deleting an NGSI-LD EntityMap. - -#### 5.14.3.2 Use case diagram {#tabuse-case-diagram-52 number="10.14.3.2"} - -A client can request the broker to completely delete an EntityMap held within the NGSI-LD system as shown in Figure 5.14.3.2-1. - -::: FL -![](./media/image68.png){style="width:3.43056in;height:2.91667in"} -::: - -::: {#Figure_5.14.3.2-1 .TF} -Figure 5.14.3.2-1: Delete EntityMap -::: - -#### 5.14.3.3 Input data {#tabinput-data-52 number="10.14.3.3"} - -EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). - -#### 5.14.3.4 Behaviour {#tabbehaviour-52 number="10.14.3.4"} - -::: B1plus -- If the EntityMap ID is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type *ResourceNotFound* shall be raised. -- The EntityMap shall be removed from the broker's internal storage, or memory. -::: - -#### 5.14.3.5 Output data {#taboutput-data-52 number="10.14.3.5"} - -None. - -### 5.14.4 Create EntityMap for Query Entities {#tabcreate-entitymap-for-query-entities number="10.14.4"} - -#### 5.14.4.1 Description {#tabdescription-53 number="10.14.4.1"} - -This operation is very similar to the Query Entities operation in [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities), except that it does not directly return Entities, but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through the included Entities. - -#### 5.14.4.2 Use case diagram {#tabuse-case-diagram-53 number="10.14.4.2"} - -A *Context Consumer* can retrieve an Entity map with the Entities that match a specific query from an NGSI-LD system as shown in [Figure 5.14.4.2‑1](10-tabapi-operation-definition.md#Figure_5.14.4.2-1). - -::: FL -![](./media/image69.png){style="width:3.41667in;height:3.125in"} -::: - -::: {#Figure_5.14.4.2-1 .TF} -Figure 5.14.4.2-1: Query Entities for creating EntityMap use case -::: - -#### 5.14.4.3 Input data {#tabinput-data-53 number="10.14.4.3"} - -::: B1plus -To simplify the operation, the same parameters as for the Query Entities operation [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) are allowed, but some of these are irrelevant for creating an Entity map and thus shall be ignored. -::: - -::: B1plus -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector. -- A list (one or more) of Entity identifiers (optional). -- A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional). -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- In the case of GeoJSON representation: -::: - -::: B2plus -- The name of the *GeoProperty* attribute to use as the geometry for the GeoJSON representation as mandated by [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) (**ignored**). -- A *datasetId* specifying which instance of the value is to be selected if the *GeoProperty* value has multiple instances as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (**ignored**). -::: - -::: B1plus -- A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- An NGSI-LD query (called context source filter, to filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- A limit to the number of Entities to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour) (**ignored**). -- A specified language filter as per [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -- A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional). -- An optional flag indicating whether to include additional [Linked Entities]{.HTML_Keyboard} corresponding to the *Relationships* retrieved and how to format those [Linked Entities]{.HTML_Keyboard}*.* See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A limit to the depth of [Linked Entities]{.HTML_Keyboard} to search whilst traversing an Entity Graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A list (one or more) of [Linked Entity identifier]{.HTML_Keyboard}s previously encountered whilst traversing an Entity Graph. See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) (optional). -- A flag indicating whether to return the location of the EntityMap used within the operation (**ignored**, EntityMap is always returned). -- A suggested expiry time for the EntityMap (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (**ignored**). -- A *datasetId* parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -- A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional). -::: - -In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the Entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. - -#### 5.14.4.4 Behaviour {#tabbehaviour-53 number="10.14.4.4"} - -::: B1plus -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names, including at least one non-system Attribute; -::: - -::: B2 -c) NGSI-LD Query, including at least one non-system Attribute; -::: - -::: B2 -d) NGSI-LD GeoQuery; -::: - -::: B2 -e) local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). -::: - -::: B1 -If none of the above is provided, then an error of type *BadRequestData* shall be raised (too wide query). -::: - -::: B1plus -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) an error of type *BadRequestData* shall be raised. -- If projection attributes are present and indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, and the use of [Linked Entity ]{.HTML_Keyboard}retrieval is not specified, or the projected attribute depth exceeds the [Linked Entity ]{.HTML_Keyboard}retrieval depth, then an error of type *BadRequestData* shall be raised. -- If the filter conditions specified by the query includes [Linked Entity]{.HTML_Keyboard} attributes, and the use of [Linked Entity ]{.HTML_Keyboard}retrieval is not specified, or the [Linked Entity ]{.HTML_Keyboard}attribute query depth exceeds the [Linked Entity ]{.HTML_Keyboard}retrieval depth, an error of type *BadRequestData* shall be raised (too deep query). -- If geometryProperty parameter is present and the Accept Header is not set to ["application/geo+json",]{.HTML_Code} then an error of type *BadRequestData* shall be raised. -- Otherwise, -::: - -- ::: B2plus - Term to URI expansion of type and Attribute names shall be performed, as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). - ::: - -- ::: B2plus - If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). - ::: - -- ::: B2plus - If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an EntityMap containing the identifiers of all the Entities found locally that meet all of the following conditions: - ::: - - ::: B3plus - - id is equal to any of the id(s) passed as a parameter; - - the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter; - - id matches the id pattern passed as a parameter. - ::: - -- ::: B2plus - Otherwise, implementations shall run a query that shall return an EntityMap containing the identifiers pf all Entities found locally that meet all of the following conditions (given the respective parameter is provided): - ::: - - ::: B3plus - - id is equal to any of the id(s) passed as a parameter; - - the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter; - - Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter; - - id matches the id pattern passed as a parameter; - - the filter conditions specified by the query are met (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); - - the geospatial restrictions imposed by the geoquery are met (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); if there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions; - - if the Scope query is present, it shall match a present Entity Scope (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.15](15-annex-c-informative-examples-of-using-the-api.md#c.5.15tabscope-queries)); - - if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list. - ::: - -::: B1plus -- Unless local scope is specified (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), for [Context Source Registrations]{.HTML_Keyboard} that match the query and support the "createEntityMapQueryEntity" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. -- For each matching [Context Source Registration]{.HTML_Keyboard}, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an EntityMap. The mapping between the Context Source Registration and the EntityMap Id is added to the *linkedMaps* element of the local EntityMap and for the Entity ids included in the returned EntityMaps a mapping to the Context Source Registration is added to the *entityMap* element of the local EntityMap. -::: - -::: B2plus -- The local EntityMap is stored and made accessible based on its identifier. -::: - -#### 5.14.4.5 Output data {#taboutput-data-53 number="10.14.4.5"} - -The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself. - -### 5.14.5 Create EntityMap for Query Temporal Evolution of Entities {#tabcreate-entitymap-for-query-temporal-evolution-of-entities number="10.14.5"} - -#### 5.14.5.1 Description {#tabdescription-54 number="10.14.5.1"} - -This operation is very similar to the Query Temporal Evolution of Entities operation in [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities), except that it does not directly return the Temporal Evolution of Entities but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through Temporal Evolution of the included Entities. - -#### 5.14.5.2 Use case diagram {#tabuse-case-diagram-54 number="10.14.5.2"} - -A *Context Consumer* can retrieve an Entity map with the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in [Figure 5.14.5.2‑1](10-tabapi-operation-definition.md#Figure_5.14.5.2-1). - -::: FL -![](./media/image70.png){style="width:3.41667in;height:3.125in"} -::: - -::: {#Figure_5.14.5.2-1 .TF} -Figure 5.14.5.2-1: Query Temporal Evolution for creating EntityMap use case -::: - -#### 5.14.5.3 Input data {#tabinput-data-54 number="10.14.5.3"} - -To simplify the operation, the same parameters as for the Query Temporal Evolution of Entities operation [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)) are allowed, but some of these are irrelevant for creating an Entity map and thus will be ignored. - -::: B1plus -- An NGSI-LD temporal query as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). -- A reference to a JSON-LD *\@context* (optional). -- A selector of Entity types as specified by [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language) (optional). Both type name (short hand string) and fully qualified type name (URI) are allowed. -- A restrictive list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be retrieved (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- An exclusionary list of Entity member names (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) to be removed (projection attributes as defined by [clause 4.21](9-tabcontext-information-management-framework.md#tabngsi-ld-attribute-projection-language)) (optional). -- A list (one or more) of Entity identifiers (optional). -- A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional). -- An id pattern as a regular expression (optional). -- An NGSI-LD query (to filter out Entities by Attribute values) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language) (optional). -- A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language) (optional). -- An NGSI-LD query (called context source filter, to filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them) as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) (optional). -- A limit to the number of Entities to be retrieved. See [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour) (**ignored**). -- A parameter (lastN) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional). -- A specified language filter as per [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter) (optional). -- A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional). -- A flag indicating whether to return the location of the EntityMap used within the operation (**ignored**, EntityMap is always returned). -- A suggested expiry time for the EntityMap (optional). -- The location of a resource holding an EntityMap of matching Entity registrations (**ignored**). -- A datasetId parameter that specifies which Attribute instances are to be selected as defined by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) (optional). -- A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional). -- In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities' types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. If the execution of the operation is limited to the local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), no further restrictions have to be provided. -::: - -#### 5.14.5.4 Behaviour {#tabbehaviour-54 number="10.14.5.4"} - -::: B1plus -- If a temporal query is not provided then an error of type *BadRequestData* shall be raised. -- At least one of the following input data shall be provided: -::: - -::: B2 -a) selector of Entity Types; -::: - -::: B2 -b) list of Attribute names, including at least one non-system Attribute; -::: - -::: B2 -c) NGSI-LD Query, including at least one non-system Attribute; -::: - -::: B2 -d) NGSI-LD GeoQuery; -::: - -::: B2 -e) local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). -::: - -::: B2 -If none of the above is provided, then an error of type *BadRequestData* shall be raised (too wide query). -::: - -::: B1plus -- If projection attributes or filter conditions indicate the use of [Linked Entity ]{.HTML_Keyboard}retrieval, an error of type *BadRequestData* shall be raised. -- If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses [4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) and [4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)) an error of type *BadRequestData* shall be raised. -- Term to URI expansion of type and Attribute names shall be observed mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- The *lastN* parameter refers to a number, *n*, of Attribute instances which shall correspond to the last *n* timestamps (in descending ordering) of the temporal property (by default *observedAt*) within the concerned temporal interval. -- Otherwise, -::: - -::: B2plus -- Let S be the set of selected Entities i.e. the query result set. -- If the split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query so that the result set contains all the Entities found locally, that meet **all** of the following conditions (given the respective parameter is provided): -- If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter. -- If an id pattern is provided, keep in S only those Entities whose id matches the id pattern. -- If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types. -- From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S4 be this new subset. -::: - -::: B1plus -- Otherwise implementations shall run a query that shall return the set of matching Entities (all Entities stored locally, in case only a local scope is specified); the logical steps to select the final result set of Entities, and the Attribute instances included as part of their temporal representation, are enumerated as follows: -::: - -::: B2plus -- If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter. -- If an id pattern is provided, keep in S only those Entities whose id matches the id pattern. -- If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types. -- From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset. -- If a values filter query is provided, from S1, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S2 be this new subset. -- If no values filter query is provided, then S2 is equal to S1. -- If geoquery is present, from S2, select those Entities whose *GeoProperty* instances meet the geospatial restrictions imposed by the geoquery (as mandated by [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language)); those geospatial restrictions shall be checked against the *GeoProperty* instances that are within the interval defined by the temporal query. Let S3 be this new subset. -- If no geoquery is provided, then S3 is equal to S2. -- If the Scope query is present, from S3, select those Entities whose Entity Scope instances match the Scope query (as mandated by [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language), for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.16](15-annex-c-informative-examples-of-using-the-api.md#c.5.16tabtemporal-scope-queries)). Let S4 be the new subset. -- If no Scope query is provided, then S4 is equal to S3. -- The local EntityMap is created based on S4. -::: - -::: B1plus -- Unless local scope is specified (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)), for [Context Source Registrations]{.HTML_Keyboard} that match the query and support the "createEntityMapQueryTemporal" operation (see operations and operation groups in [clause 4.20](9-tabcontext-information-management-framework.md#tabngsi-ld-distributed-operation-names)), implementations shall do the following: -::: - -::: B2plus -- If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. -- For each matching Context[Source Registration]{.HTML_Keyboard}, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an EntityMap. The mapping between the Context Source Registration and the EntityMap Id is added to the *linkedMaps* element of the local EntityMap and for the Entity ids included in the returned Entity Maps a mapping to the Context Source Registration is added to the *entityMap* element of the local EntityMap. -::: - -::: B1plus -- The local EntityMap is stored and made accessible based on its identifier. -::: - -#### 5.14.5.5 Output Data {#taboutput-data-54 number="10.14.5.5"} - -::: ondemand_PAR_space_after_10 -The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself. -::: - -## 5.15 Context Source Identity Information {#tabcontext-source-identity-information number="10.15"} - -### 5.15.1 Retrieve Context Source Identity Information {#tabretrieve-context-source-identity-information number="10.15.1"} - -#### 5.15.1.1 Description {#tabdescription-55 number="10.15.1.1"} - -With this operation, a client can obtain [Context Source]{.HTML_Keyboard} identity information which uniquely defines the [Context Source]{.HTML_Keyboard} itself. In the multi-tenancy use case (see [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)), a client can obtain identify information about a specific [Tenant]{.HTML_Keyboard} within a [Context Source]{.HTML_Keyboard}. - -#### 5.15.1.2 Use case diagram {#tabuse-case-diagram-55 number="10.15.1.2"} - -A client can request the broker to retrieveidentity information about a specific [Context Source]{.HTML_Keyboard} within the NGSI-LD system as shown in [Figure 5.15.1.2‑1](10-tabapi-operation-definition.md#Figure_5.15.1.2-1). - -::: FL -![](./media/image71.png){style="width:3.43056in;height:3.15278in"} -::: - -::: {#Figure_5.15.1.2-1 .TF} -Figure 5.15.1.2-1: Retrieve Context Source Identity Information -::: - -#### 5.15.1.3 Input data {#tabinput-data-55 number="10.15.1.3"} - -None. - -#### 5.15.1.4 Behaviour {#tabbehaviour-55 number="10.15.1.4"} - -::: B1plus -- If the [Context Source]{.HTML_Keyboard} is unable to supply identity information about itself, then error of type *NotImplemented* shall be raised. -- Return a JSON-LD object representing the identity of the [Context Source]{.HTML_Keyboard} itself as mandated by [clause 5.2.40](10-tabapi-operation-definition.md#tabcontext-source-identity). This can also include additional configurational data dependent on the specific[Context Source]{.HTML_Keyboard} implementation. -::: - -#### 5.15.1.5 Output data {#taboutput-data-55 number="10.15.1.5"} - -A JSON-LD object representing the identity of the [Context Source]{.HTML_Keyboard} as mandated by [clause 5.2.40](10-tabapi-operation-definition.md#tabcontext-source-identity). - -## 5.16 Snapshot Functionality {#tabsnapshot-functionality number="10.16"} - -### 5.16.1 Create Snapshot {#tabcreate-snapshot number="10.16.1"} - -#### 5.16.1.1 Description {#tabdescription-56 number="10.16.1.1"} - -This operation allows creating a new snapshot. - -#### 5.16.1.2 Use case diagram {#tabuse-case-diagram-56 number="10.16.1.2"} - -A *Context Consumer* can create a new snapshot to have a more consistent basis for queries on the persisted Entity information as shown in [Figure 5.16.1.2‑1](10-tabapi-operation-definition.md#Figure_5.16.1.2-1). - -::: FL -![](./media/image72.png){style="width:3.41667in;height:2.95833in"} -::: - -::: {#Figure_5.16.1.2-1 .TF} -Figure 5.16.1.2-1: Create Snapshot use case -::: - -#### 5.16.1.3 Input data {#tabinput-data-56 number="10.16.1.3"} - -::: B1plus -- A JSON-LD document conforming to the *Snapshot* data type as mandated by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot). -::: - -#### 5.16.1.4 Behaviour {#tabbehaviour-56 number="10.16.1.4"} - -::: B1plus -- If the data types, cardinalities and restrictions expressed by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot) are not met, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD endpoint already knows about this Snapshot, as there is an existing Snapshot whose id (URI) is equivalent, an error of type *AlreadyExists* shall be raised. -- If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. -- The *createdAt* and *modifiedAt* timestamps are set to the current time of the NGSI-LD system. -- The *snapshotStatus* member is set to *preparation*. -- The *expiresAt* member shall be set, taking into account the *snapshotLifetime* requested, but applying the configured limit of the NGSI-LD system. -- If the Snapshot document does not include a *snapshotPriority*, the *snapshotPriority* shall be set to 5. -- The request returns, confirming the creation of the snapshot to the requesting *Context Consumer, providing the Snapshot identifier*. The status is accessible to the *Context Consumer* as described in [clause 5.16.3](10-tabapi-operation-definition.md#tabretrieve-snapshot-status). The following is executed in the background. -- Implementations shall execute the Queries specified in the *snapshotQueries* member, in each case following the behaviour described in [clause 5.7.2.4](10-tabapi-operation-definition.md#tabbehaviour-22). If the size of the respective results require pagination, all pages are to be retrieved completely. The response details for each query execution (aggregated across paginated ones) shall be stored in the s*napshotQueryDetails* list, at the same position as the query in *snapshotQueries.* -- Implementations shall execute the Temporal Queries specified in the *snapshotTemporalQueries* member, in each case following the behaviour described in [clause 5.7.4.4](10-tabapi-operation-definition.md#tabbehaviour-24). If the size of the respective results require pagination, all pages are to be retrieved completely. The response details for each query execution (aggregated across paginated ones) shall be stored in the s*napshotTemporalQueryDetails* list, at the same position as the query in *snapshotTemporalQueries.* -- The retrieved Entity information shall be stored by the NGSI-LD system, so that local NGSI-LD operations can then be executed on it. -- After all information has been stored, the *snapshotStatus* member is set to *success*, if all queries and temporal queries were executed successfully and yielded at least one result, to *partial*, if at least one query or temporal query was executed successfully and yielded a result, to *empty*, if at least one query or temporal query was executed successfully, but without yielding a result, and to *failure* otherwise*.* -- If the *endpoint* member is present, a Snapshot notification is sent as described in [clause 5.16.6](10-tabapi-operation-definition.md#tabsnapshot-status-notification-behaviour). -::: - -#### 5.16.1.5 Output data {#taboutput-data-56 number="10.16.1.5"} - -A URI identifying the newly created Snapshot. - -### 5.16.2 Clone Snapshot {#tabclone-snapshot number="10.16.2"} - -#### 5.16.2.1 Description {#tabdescription-57 number="10.16.2.1"} - -This operation allows cloning a snapshot stored in an NGSI-LD system. - -#### 5.16.2.2 Use case diagram {#tabuse-case-diagram-57 number="10.16.2.2"} - -A *Context Consumer* can clone an existing snapshot stored in an NGSI-LD system as shown in [Figure 5.16.2.2‑1](10-tabapi-operation-definition.md#Figure_5.16.2.2-1). - -::: FL -![](./media/image73.png){style="width:3.41667in;height:2.95833in"} -::: - -::: {#Figure_5.16.2.2-1 .TF} -Figure 5.16.2.2-1: Clone Snapshot use case -::: - -#### 5.16.2.3 Input data {#tabinput-data-57 number="10.16.2.3"} - -::: B1plus -- A URI identifying the Snapshot to be cloned. -- A JSON-LD document conforming to the *Snapshot* data type as mandated by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot), but without *snapshotQueriesDetails* and *snapshotQueriesTemporalDetails* elements. -::: - -#### 5.16.2.4 Behaviour {#tabbehaviour-57 number="10.16.2.4"} - -::: B1plus -- If the data types, cardinalities and restrictions expressed by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot) are not met, then an error of type *BadRequestData* shall be raised. -- If the identifier of the Snapshot to be cloned is not found, an error of type *ResourceNotFound* shall be raised. -- If the Snapshot document includes a Snapshot identifier and there is an existing Snapshot whose id (URI) is equivalent, an error of type *AlreadyExists* shall be raised. -- If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. -- The *createdAt* and *modifiedAt* timestamps of the clone are set to the current time of the NGSI-LD system. -- The *snapshotStatus* member of the clone is set to *preparation*. -- The *expiresAt* member shall be set, taking into account the *snapshotLifetime* requested, but applying the configured limit of the NGSI-LD system. -- The request returns, confirming the creation of the cloned Snapshot to the requesting *Context Consumer*. The status is accessible to the *Context Consumer* as described in [clause 5.16.3](10-tabapi-operation-definition.md#tabretrieve-snapshot-status). The following is executed in the background. -- All Entity and Temporal Evolution of Entity data that is part of the Snapshot to be cloned is copied to the clone Snapshot. -- After all information has been stored, the *snapshotStatus* member is set to *success,* if cloning was successful, and to *failure* otherwise*.* -- If the *endpoint* member is present, a Snapshot notification is sent as described in [clause 5.16.6](10-tabapi-operation-definition.md#tabsnapshot-status-notification-behaviour). -::: - -#### 5.16.2.5 Output data {#taboutput-data-57 number="10.16.2.5"} - -A URI identifying the newly created Snapshot. - -### 5.16.3 Retrieve Snapshot Status {#tabretrieve-snapshot-status number="10.16.3"} - -#### 5.16.3.1 Description {#tabdescription-58 number="10.16.3.1"} - -This operation allows retrieving the status of a Snapshot stored in an NGSI-LD system. - -#### 5.16.3.2 Use case diagram {#tabuse-case-diagram-58 number="10.16.3.2"} - -A *Context Consumer* can retrieve the status of a Snapshot from an NGSI-LD system as shown in [Figure 5.16.3.2‑1](10-tabapi-operation-definition.md#Figure_5.16.3.2-1). - -::: ondemand_PAR_alignment_CENTER -![](./media/image74.png){style="width:3.41667in;height:3.16667in"} -::: - -::: {#Figure_5.16.3.2-1 .TF} -Figure 5.16.3.2-1: Retrieve Snapshot Status use case -::: - -#### 5.16.3.3 Input data {#tabinput-data-58 number="10.16.3.3"} - -Snapshot Id (URI) of the Snapshot whose status is to be retrieved. - -#### 5.16.3.4 Behaviour {#tabbehaviour-58 number="10.16.3.4"} - -::: B1plus -- If the Snapshot Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the identifier provided does not correspond to any existing Snapshot in the system, then an error of type *ResourceNotFound* shall be raised. -- Otherwise, implementations shall retrieve the Snapshot status and return it to the caller. -::: - -#### 5.16.3.5 Output data {#taboutput-data-58 number="10.16.3.5"} - -A JSON-LD object representing the Snapshot status as mandated by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot). - -### 5.16.4 Update Snapshot Status {#tabupdate-snapshot-status number="10.16.4"} - -#### 5.16.4.1 Description {#tabdescription-59 number="10.16.4.1"} - -This operation allows updating an existing Snapshot. - -#### 5.16.4.2 Use case diagram {#tabuse-case-diagram-59 number="10.16.4.2"} - -A *Context Consumer* can update an existing Snapshot within an NGSI-LD system as shown in [Figure 5.16.4.2‑1](10-tabapi-operation-definition.md#Figure_5.16.4.2-1). - -::: FL -![](./media/image75.png){style="width:3.41667in;height:3.26389in"} -::: - -::: {#Figure_5.16.4.2-1 .TF} -Figure 5.16.4.2-1: Update Snapshot Status use case -::: - -#### 5.16.4.3 Input data {#tabinput-data-59 number="10.16.4.3"} - -::: B1plus -- Snapshot identifier (URI), the target Snapshot. -- A JSON-LD document representing a Snapshot Fragment -::: - -#### 5.16.4.4 Behaviour {#tabbehaviour-59 number="10.16.4.4"} - -::: B1plus -- If the Snapshot id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the NGSI-LD System does not know about the target Snapshot, because there is no existing Snapshot whose id (URI) is equivalent, an error of type *ResourceNotFound* shall be raised. -- Execute the behaviour defined in [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation) on JSON-LD validation. -- If the data types and restrictions expressed by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot) are not met by the *Snapshot Fragment* - in particular whether elements can be updated - then an error of type *BadRequestData* shall be raised. -- Term to URI expansion of Attribute names shall be observed as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- Then, implementations shall modify the target Snapshot as mandated by [clause 5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour). -::: - -#### 5.16.4.5 Output data {#taboutput-data-59 number="10.16.4.5"} - -A JSON-LD object representing the Snapshot status as mandated by [clause 5.2.41](10-tabapi-operation-definition.md#tabsnapshot). - -### 5.16.5 Delete Snapshot {#tabdelete-snapshot number="10.16.5"} - -#### 5.16.5.1 Description {#tabdescription-60 number="10.16.5.1"} - -This operation allows deleting an existing Snapshot. - -#### 5.16.5.2 Use case diagram {#tabuse-case-diagram-60 number="10.16.5.2"} - -A *Context Consumer* can delete a Snapshot within an NGSI-LD system as shown in [Figure 5.16.5.2‑1](10-tabapi-operation-definition.md#Figure_5.16.5.2-1). - -::: FL -![](./media/image76.png){style="width:3.41667in;height:2.95833in"} -::: - -::: {#Figure_5.16.5.2-1 .TF} -Figure 5.16.5.2-1: Delete Snapshot use case -::: - -#### 5.16.5.3 Input data {#tabinput-data-60 number="10.16.5.3"} - -::: B1plus -- A Snapshot identifier (URI), the target Snapshot. -::: - -#### 5.16.5.4 Behaviour {#tabbehaviour-60 number="10.16.5.4"} - -::: B1plus -- If the Snapshot Id is not present or it is not a valid URI, then an error of type *BadRequestData* shall be raised. -- If the Snapshot id provided does not correspond to any existing Snapshot in the system, then an error of type *ResourceNotFound* shall be raised. -- Otherwise implementations shall delete the Snapshot. -::: - -#### 5.16.5.5 Output data {#taboutput-data-60 number="10.16.5.5"} - -None. - -### 5.16.6 Snapshot status notification behaviour {#tabsnapshot-status-notification-behaviour number="10.16.6"} - -A Snapshot status notification allows the subscriber, typically the creator of the Snapshot, to be notified when the Snapshot is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour: - -::: B1plus -- SnapshotNotification [(clause 5.3.4](10-tabapi-operation-definition.md#tabsnapshotnotification)) messages can only be sent, if the *endpoint* member is set. -- SnapshotNotification messages are sent to the URI specified in the *endpoint* member of the Snapshot status. -- The information in the *receiverInfo* member of the Snapshot status shall be added to the SnapshotNotification message in the way required for the binding protocol. -- Snapshot Status Notifications shall be sent after all the specified Snapshot queries have been executed, the query results have been integrated and the Snapshot status has been updated accordingly. -- Snapshot status Notifications shall also be sent after any Snapshot status update, e.g. informing about the actual updated expiresAt timestamp. -- The SnapshotNotification shall be as mandated by [clause 5.3.4](10-tabapi-operation-definition.md#tabsnapshotnotification). -::: - -### 5.16.7 Purge Snapshots {#tabpurge-snapshots number="10.16.7"} - -#### 5.16.7.1 Description {#tabdescription-61 number="10.16.7.1"} - -This operation allows purging selected Snapshots. - -#### 5.16.7.2 Use case diagram {#tabuse-case-diagram-61 number="10.16.7.2"} - -A *Context Consumer* can purge Snapshots within an NGSI-LD system as shown in [Figure 5.16.7.2‑1](10-tabapi-operation-definition.md#Figure_5.16.7.2-1). - -::: FL -![](./media/image77.png){style="width:3.41667in;height:2.95833in"} -::: - -::: {#Figure_5.16.7.2-1 .TF} -Figure 5.16.7.2-1: Purge Snapshots use case -::: - -#### 5.16.7.3 Input data {#tabinput-data-61 number="10.16.7.3"} - -::: B1plus -- An NGSI-LD Query to select fitting Snapshots to be purged based on members of the Snapshot data type (see [Table 5.2.41‑1](10-tabapi-operation-definition.md#Table_5.2.41-1)), as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). -::: - -#### 5.16.7.4 Behaviour {#tabbehaviour-61 number="10.16.7.4"} - -::: B1plus -- If the NGSI-LD Query is not present or it is not a valid as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language), restricted to members of the Snapshot data type, then an error of type *BadRequestData* shall be raised. -- Implementations shall purge the Snapshots fitting the NGSI-LD Query. -::: - -#### 5.16.7.5 Output data {#taboutput-data-61 number="10.16.7.5"} - -None. diff --git a/API-md/11-tabapi-http-binding.md b/API-md/11-tabapi-http-binding.md deleted file mode 100644 index 8d0932890978d44e05917c0d7b74fafab662b4a3..0000000000000000000000000000000000000000 --- a/API-md/11-tabapi-http-binding.md +++ /dev/null @@ -1,4879 +0,0 @@ -# 6 API HTTP Binding {#tabapi-http-binding number="11"} - -## 6.1 Introduction {#tabintroduction-21 number="11.1"} - -This clause defines the resources and operations of the NGSI-LD API. The NGSI-LD API is structured in terms of HTTP [[3]](7-tabreferences.md#3), [[4]](7-tabreferences.md#4) verbs, request and response payload bodies. - -A non-normative OAS specification [[i.12]](7-tabreferences.md#i.12) of the referred HTTP binding can be found at [[i.14]](7-tabreferences.md#i.14). - -## 6.2 Global Definitions and Resource Structure {#tabglobal-definitions-and-resource-structure number="11.2"} - -All resource URIs of this API shall have the following root: - -::: B1plus -- {apiRoot}/{apiName}/{apiVersion}/ -::: - -::: NO -NOTE 1: - -The *apiRoot* discovery process is out of the scope of the present document. -::: - -::: NO -NOTE 2: - -The *apiRoot* for [Context Source]{.HTML_Keyboard} related aspects and the *apiRoot* for general Entity-related aspects can be different, e.g. the [Context Source]{.HTML_Keyboard} related aspects can be implemented by a [Context Registry]{.HTML_Keyboard} as shown for the distributed and federated architectures (see [clause 4.3](9-tabcontext-information-management-framework.md#tabngsi-ld-architectural-considerations) ), whereas the Entity-related aspects would be implemented by a [Context Broker]{.HTML_Keyboard} . -::: - -::: NO -NOTE 3: - -The *apiRoot* for [Context Source]{.HTML_Keyboard} related aspects and the *apiRoot* for general Entity-related aspects can be different than the *apiRoot* for temporal aspects, e.g. the temporal aspects can be implemented by an NGSI-LD subsystem specialized in historical data. -::: - -The *apiRoot* includes the scheme ("http" or "https"), host and optional port, and an optional prefix string. The API shall support HTTP over TLS (also known as HTTPS - see IETF RFC 2818 [[18]](7-tabreferences.md#18)). TLS version 1.2 as defined by IETF RFC 5246 [[19]](7-tabreferences.md#19) shall be supported. HTTP without TLS is not recommended. - -The *apiName* shall be set to ["ngsi-ld"]{.HTML_Code} and the *apiVersion* shall be set to ["v1"]{.HTML_Code} for the present document. - -All resource URIs are defined relative to the above root URI. The structure of the resources under the root URI is shown in [Figure 6.2‑1](11-tabapi-http-binding.md#Figure_6.2-1) and methods defined on them are shown in [Table 6.2‑1](11-tabapi-http-binding.md#Table_6.2-1). - -An OpenAPI companion specification is available, see [[37]](7-tabreferences.md#37). - -::: FL -![](./media/image78.png){style="width:3.27719in;height:9.49467in"} -::: - -::: {#Figure_6.2-1 .TF} -Figure 6.2-1: Resource URI structure of the NGSI-LD API -::: - -::: {#Table_6.2-1 .TH} -Table 6.2-1: Resources and HTTP methods defined on them -::: - -::: TAC -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Resource Name | Resource URI | HTTP Method | Meaning | Clauses | -+===========================================================+============================================================+=============+==========================================================================================================+===========================+ -| Entity List | /entities/ | POST | Entity creation | 5.6.1; 6.4.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | Query entities | 5.7.2; 6.4.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Purge entities | 5.6.21; 6.4.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity by id | /entities/{entityId} | GET | Entity retrieval by id | 5.7.1; 6.5.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Entity deletion by id | 5.6.6; 6.5.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Entity merge by id | 5.6.17; 6.5.3.4 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PUT | Entity replacement by id | 5.6.18; 6.5.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Attribute List | /entities/{entityId}/attrs/ | POST | Append Attributes to Entity | 5.6.3; 6.6.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Update Attributes of an Entity | 5.6.2; 6.6.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Attribute by id | /entities/{entityId}/attrs/{attrId} | PATCH | Partial Attribute update | 5.6.4; 6.7.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Attribute deletion | 5.6.5; 6.7.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PUT | Attribute replacement | 5.6.19; 6.7.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Subscriptions List | /subscriptions/ | POST | Create Subscription | 5.8.1; 6.10.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | Retrieve list of Subscriptions | 5.8.4; 6.10.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Subscription by Id | /subscriptions/{subscriptionId} | GET | Subscription retrieval by id | 5.8.3; 6.11.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Subscription update by id | 5.8.2; 6.11.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Subscription deletion by id | 5.8.5; 6.11.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Types | /types/ | GET | Retrieve available entity types | 5.7.5 and 5.7.6; 6.25.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Type | /types/{type} | GET | Details about available entity type | 5.7.7; 6.26.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Attributes | /attributes/ | GET | Available attributes | 5.7.8 and 5.7.9; 6.27.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Attribute | /attributes/{attrId} | GET | Details about available attribute | 5.7.10; 6.28.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Context source registration list | /csourceRegistrations/ | POST | Csource registration creation | 5.9.2; 6.8.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | Discover Csource registrations | 5.10.2; 6.8.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Context source registration by Id | /csourceRegistrations/{registrationId} | GET | Csource registration retrieval by id | 5.10.1; 6.9.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Csource registration update by id | 5.9.3; 6.9.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Csource registration deletion by id | 5.9.4; 6.9.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Context source registration subscription list | /csourceSubscriptions/ | POST | Create subscription to Csource registration | 5.11.2; 6.12.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | Retrieval of list of subscription to Csource registration | 5.11.5; 6.12.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Context source registration subscription by Id | /csourceSubscriptions/{subscriptionId} | GET | Csource registration subscription retrieval by id | 5.11.4; 6.13.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Csource registration subscription update by id | 5.11.3; 6.13.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Csource registration subscription deletion by id | 5.11.6; 6.13.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. Create | /entityOperations/create | POST | Batch Entity creation | 5.6.7; 6.14.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. Upsert | /entityOperations/upsert | POST | Batch Entity creation or update (upsert) | 5.6.8; 6.15.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. Update | /entityOperations/update | POST | Batch Entity update | 5.6.9; 6.16.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. Delete | /entityOperations/delete | POST | Batch Entity deletion | 5.6.10; 6.17.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. Query | /entityOperations/query | POST | Query entities based on POST | 5.7.2; 6.23.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Entity Operations. | /entityOperations/merge | POST | Batch Entity merge | 5.6.20; 6.31.3.1 | -| | | | | | -| Merge | | | | | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Evolution of Entities | /temporal/entities/ | POST | Temporal Evolution of an Entity creation | 5.6.11; 6.18.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | Query Temporal Evolution of Entities | 5.7.4; 6.18.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Evolution of an Entity by id | /temporal/entities/{entityId} | GET | Temporal Evolution of an Entity retrieval by id | 5.7.3; 6.19.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Temporal Evolution of an Entity deletion by id | 5.6.16; 6.18.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Representation of Attribute List | /temporal/entities/{entityId}/attrs/ | POST | Temporal Evolution of Attribute of an Entity instance addition | 5.6.12; 6.20.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Representation of Attribute by id | /temporal/entities/{entityId}/attrs/{attrId} | DELETE | Attribute from Temporal Evolution of an Entity deletion | 5.6.13; 6.21.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Representation of Attribute Instance by id | /temporal/entities/{entityId}/attrs/{attrId} /{instanceId} | PATCH | Attribute Instance from Temporal Evolution of an Entity update by instance id | 5.6.14; 6.22.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Attribute Instance from Temporal Evolution of an Entity deletion by instance id | 5.6.15; 6.22.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Create EntityMap for Query Temporal Evolution of Entities | /temporal/entityMaps/ | GET | Query temporal evolution of entities for creating entity map | 5.15.4; | -| | | | | | -| | | | | 6.35.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | POST | Query temporal evolution of entities for creating entity map based on POST | 5.15.4; | -| | | | | | -| | | | | 6.35.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Temporal Query Operation | /temporal/entityOperations/query | POST | Query Temporal Evolution of Entities based on POST | 5.7.4; 6.24.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Add and List \@context | /jsonldContexts | POST | Add a user \@context to the internal cache | 5.13.2; 6.29.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | GET | List all cached \@contexts | 5.13.3; 6.29.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Serve, Delete and Reload \@context | /jsonldContexts/{contextId} | GET | Serve one specific user \@context | 5.13.4; 6.30.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Delete one specific \@context from internal cache, possibly re-inserting a freshly downloaded copy of it | 5.13.5; 6.30.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Create EntityMap for Query Entities | /entityMaps/ | GET | Query entities for creating entity map | 5.14.4; | -| | | | | | -| | | | | 6.34.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | POST | Query entities for creating entity map based on POST | 5.14.4; | -| | | | | | -| | | | | 6.34.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Retrieve, Update and Delete Entity Maps | /entityMaps/{entityMapId} | GET | EntityMap Retrieval by id | 5.14.1; 6.32.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | EntityMap Update by id | 5.14.2; 6.32.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | EntityMap Deletion by id | 5.14.3; 6.32.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Retrieve Context Source Identity Information | /info/sourceIdentity | GET | Context Source Identity Retrieval | 5.15.1; 6.33.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Create Snapshot or Purge Snapshots | /snapshots/ | POST | Create Snapshot | 5.16.1; | -| | | | | | -| | | | | 6.36.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Purge Snapshots | 5.16.7; | -| | | | | | -| | | | | 6.36.3.2 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Retrieve and Update Snapshot Status or Delete Snapshot | /snapshots/{snapshotId} | GET | Retrieve Snapshot Status | 5.16.3; | -| | | | | | -| | | | | 6.37.3.1 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | PATCH | Update Snapshot Status | 5.16.4; | -| | | | | | -| | | | | 6.37.3.2 | -| | +-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| | | DELETE | Delete Snapshot | 5.16.5; | -| | | | | | -| | | | | 6.37.3.3 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -| Clone Snapshot | /snapshots/{snapshotId}/clone | POST | Clone Snapshot | 5.16.2; | -| | | | | | -| | | | | 6.38.3.1 | -+-----------------------------------------------------------+------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+---------------------------+ -::: - -## 6.3 Common Behaviours {#tabcommon-behaviours-1 number="11.3"} - -### 6.3.1 Introduction {#tabintroduction-22 number="11.3.1"} - -This clause extends the API common behaviours to the particularities of the HTTP REST binding. For each operation implementations shall exhibit the common behaviours as specified by [clause 5.5](10-tabapi-operation-definition.md#tabcommon-behaviours) and the behaviours defined by the present clause. - -### 6.3.2 Error Types {#taberror-types-1 number="11.3.2"} - -This clause associates API error types (which shall be contained in the response payload body) defined by [clause 5.5.2](10-tabapi-operation-definition.md#taberror-types) with HTTP status codes as shown in [Table 6.3.2‑1](11-tabapi-http-binding.md#Table_6.3.2-1). - -::: {#Table_6.3.2-1 .TH} -Table 6.3.2-1: Mapping of error types to HTTP status codes -::: - -::: TAL -+-----------------------------------------------------------+-----------------------------------+ -| Error Type | HTTP status | -+===========================================================+===================================+ -| https://uri.etsi.org/ngsi-ld/errors/AlreadyExists | {TAC} | -| | | -| | 409 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/BadRequestData | {TAC} | -| | | -| | 400 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/InternalError | {TAC} | -| | | -| | 500 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/InvalidRequest | {TAC} | -| | | -| | 400 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable | {TAC} | -| | | -| | 504 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport | {TAC} | -| | | -| | 501 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant | {TAC} | -| | | -| | 404 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported | {TAC} | -| | | -| | 422 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound | {TAC} | -| | | -| | 404 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery | {TAC} | -| | | -| | 403 | -+-----------------------------------------------------------+-----------------------------------+ -| https://uri.etsi.org/ngsi-ld/errors/TooManyResults | {TAC} | -| | | -| | 403 | -+-----------------------------------------------------------+-----------------------------------+ -::: - -In addition, implementations shall support the standard specific errors of HTTP bindings, such as the following: - -::: B1plus -- "Method Not Allowed" (405) which shall be raised when a client invokes a wrong HTTP verb over a resource. Implementations shall provide the allowed HTTP methods as mandated by IETF RFC 7231 [[3]](7-tabreferences.md#3) in section 6.5.5. -- "Request Entity too large" (413) which shall be raised when the HTTP input data stream provided by a client was too large i.e. too many bytes. -- "Length required" (411) which shall be raised when an HTTP request provided by a client does not define the "Content-Length" HTTP header. -- "Unsupported Media Type" (415) which shall be raised when an HTTP request payload body (as per the "Content-Type" header) it is not ["application/json"]{.HTML_Code} nor ["application/ld+json"]{.HTML_Code}. -- "Not [Acceptable" 406](#Table_406)) which shall be raised when the response media types that are acceptable by a client (as per the "Accept" header) do not include or expand to ["application/json"]{.HTML_Code} nor ["application/ld+json"]{.HTML_Code}*.* -::: - -### 6.3.3 Reporting errors {#tabreporting-errors number="11.3.3"} - -When an API operation results in an error, implementations shall return an HTTP response as follows: - -::: B1plus -- Content-Type: application/json. -- HTTP Status Code: As per [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1) depending on error type. -- Payload body: A JSON object including all the terms defined by [clause 5.5.3](10-tabapi-operation-definition.md#taberror-response-payload-body). -::: - -### 6.3.4 HTTP request preconditions {#tabhttp-request-preconditions number="11.3.4"} - -For HTTP POST, PATCH and PUT HTTP requests implementations shall check the following preconditions: - -::: B1plus -- Content-Type header shall be ["application/json"]{.HTML_Code} or ["application/ld+json"]{.HTML_Code}*.* -- Content-Length header shall include the length of the request payload body. -::: - -For HTTP PATCH requests ["application/merge-patch+json"]{.HTML_Code} is allowed as Content-Type, as mandated by IETF RFC 7396 [[16]](7-tabreferences.md#16). Implementations shall interpret such MIME type as equivalent to ["application/json"]{.HTML_Code}*.* - -For HTTP GET requests and for HTTP POST operations corresponding to "Query Entities" (see [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) and "Query Temporal Evolutions of Entities" (see [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)), implementations shall check the following preconditions: - -::: B1plus -- Accept header shall include (or define a media range that can be expanded to) at least one of: -::: - -::: B2plus -- ["application/json"]{.HTML_Code} -- ["application/ld+json"]{.HTML_Code} -- ["application/geo+json"]{.HTML_Code} -::: - -The order of the list above is significant. If the Accept header can be expanded to more than one of the options of the list, the first one of the list shall be selected, unless amended by the HTTP Accept header processing rules, e.g. the presence of a ["q"]{.HTML_Code} parameter indicating a relative weight, (as mandated by IETF RFC 7231 [[3]](7-tabreferences.md#3), section 5.3.2) require otherwise. - -If the Accept header is not present, ["application/json"]{.HTML_Code} shall be assumed. - -If an incoming HTTP request does not meet the preconditions stated above, an HTTP error response of type *InvalidRequest* shall be returned, with the following exceptions: - -::: B1plus -- "Content-Length" HTTP header absence, shall result in just a **411** HTTP status code (without any payload body). -- Unsupported Media Type, i.e. "Content-Type" header is not ["application/json"]{.HTML_Code} nor ["application/ld+json"]{.HTML_Code}, shall result in just a **415** HTTP status code (without any payload body). -- Not Acceptable Media Type, i.e. "Accept" header does not imply ["application/json"]{.HTML_Code} nor ["application/ld+json"]{.HTML_Code}, shall result in a **406** HTTP status code and the body of the message shall contain the list of the available representations of the resources. -::: - -Notwithstanding the above, if the Accept Header is set to ["application/geo+json"]{.HTML_Code}: - -::: B1plus -- For Context Information Consumption operations only, specifically "Retrieve Entity" (see [clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)) and "Query Entity" [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) GeoJSON is considered as an acceptable content type and a GeoJSON payload will be returned. -- For all other operations, the request will result in a Not Acceptable Media Type error, returning a **406** HTTP status code and the body of the message shall contain the list of the available representations of the resources. -::: - -### 6.3.5 JSON-LD \@context resolution {#tabjson-ld-context-resolution number="11.3.5"} - -In the HTTP REST binding, implementations shall resolve the JSON-LD @*context* associated to an incoming HTTP request as follows: - -::: B1plus -- If the request verb is GET or DELETE, then the associated JSON-LD *\@context* shall be obtained from a Link header [[7]](7-tabreferences.md#7) as mandated by JSON-LD [[2]](7-tabreferences.md#2), section 6.2. In the absence of such Link header, then the associated *\@context* shall be the default JSON-LD *\@context*. -::: - -::: EX -EXAMPLE: - -The structure of the referred Link header is shown below. The first component (between [< >]{.HTML_Code} ) is a dereferenceable URI pointing to the JSON-LD document which contains the *\@context* to be used to expand the terms used by the corresponding operation. The second parameter is a fixed, non-dereferenceable URI used to denote a unique identifier and semantics for this header (marking it as a link to a JSON-LD *\@context* ). The third and final parameter flags the MIME type of the linked resource (JSON-LD). -::: - -::: B1plus -- If the request verb is POST, PATCH or PUT and the Content-Type header is ["application/json"]{.HTML_Code}, then the *\@context* shall be obtained from a Link Header as mandated by JSON-LD [[2]](7-tabreferences.md#2), section 6.2. In the absence of such Link Header, then the *\@context* shall be the default *\@context*. In any case, if the request payload body (as JSON) contains a *\@context* term, then an HTTP error response of type *BadRequestData* shall be raised. -- If the request verb is POST, PATCH or PUT and the Content-Type header is ["application/ld+json",]{.HTML_Code} then the associated *\@context* shall be obtained from the request payload body itself. If no *\@context* can be obtained from the request payload body, then an HTTP error response of type *BadRequestData* shall be raised. In any case, the presence of a JSON-LD Link header in the incoming HTTP request when the Content-Type header is ["application/ld+json"]{.HTML_Code} shall result in an HTTP error response of type *BadRequestData*. -::: - -In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is ["application/ld+json",]{.HTML_Code} then the associated *\@context* shall be provided only as part of the request payload body. Likewise, if MIME type is ["application/json"]{.HTML_Code}, then the associated *\@context* shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise. - -In contrast, GET and DELETE operations always take their input *\@context* from the JSON-LD Link Header. - -### 6.3.6 HTTP response common requirements {#tabhttp-response-common-requirements number="11.3.6"} - -Implementations shall honour the Accept header provided by HTTP requests as mandated by [clause 6.3.4](11-tabapi-http-binding.md#tabhttp-request-preconditions): - -::: B1plus -- If the target response's MIME type is ["application/json"]{.HTML_Code} such response shall include a Link to the associated JSON-LD *\@context* as mandated by [[2]](7-tabreferences.md#2), section 6.2. -::: - -::: B2plus -- If the Prefer header [[26]](7-tabreferences.md#26) is set to ["ngsi-ld="]{.HTML_Code} then implementations shall set the Preference-Applied header to ["ngsi-ld="]{.HTML_Code} in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). -::: - -::: B1plus -- If the target response's MIME type is ["application/ld+json",]{.HTML_Code} then the response payload body provided by the HTTP response shall include a JSON-LD *\@context*. -::: - -::: B2plus -- If the Prefer Header [[26]](7-tabreferences.md#26) is set to ["ngsi-ld="]{.HTML_Code} then implementations shall set Preference-Applied header to ["ngsi-ld="]{.HTML_Code} in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). -::: - -::: B1plus -- If the target response's MIME type is ["application/geo+json"]{.HTML_Code} and the Prefer Header [[26]](7-tabreferences.md#26) is omitted or set to ["body=ld+json",]{.HTML_Code} then the response payload body provided by the HTTP response shall include a JSON-LD *\@context*, and the representation of the entities shall be in GeoJSON format in the response payload body. -- If the target response's MIME type is ["application/geo+json"]{.HTML_Code} and the Prefer Header [[26]](7-tabreferences.md#26) is set to ["body=json"]{.HTML_Code} such response shall include a Link to the associated JSON-LD *\@context* as mandated by [[2]](7-tabreferences.md#2), section 6.2 and the representation of the entities shall be in GeoJSON format in the response payload body, and *\@context* shall be omitted from the payload body. -::: - -Operations where the response payload body is not present such as successful HTTP POST, PATCH, PUT or DELETE operations and all error responses, do not include the Link header in the response. - -Operations that result in an error that return a payload or that result in a partial success (207 Multi-Status) shall always respond with MIME type ["application/json"]{.HTML_Code}*,* regardless of the Accept header. It is assumed that if a client application understands any of the supported MIME types, the application shall understand ["application/json"]{.HTML_Code} errors. Only Fully Qualified Names shall be used in the payload body of error or partial success responses, as there is no context present. - -No Content-Length HTTP header shall be present if the response code is 204. - -### 6.3.7 Representation of Entities {#tabrepresentation-of-entities number="11.3.7"} - -For HTTP GET and POST operations corresponding to "Retrieve Entity" (see [clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)) and "Query Entities" (see [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)), [Context Broker]{.HTML_Keyboard} implementations shall support the parameter specified in [Table 6.3.7‑1](11-tabapi-http-binding.md#Table_6.3.7-1), which specifies all possible supported representations formats. - -In contrast, at a minimum, registered [Context Source]{.HTML_Keyboard} implementations shall support the normalized representation of Entities as default. When a registered [Context Source]{.HTML_Keyboard} is unable to support additional representations, a 501 Not Implemented Error shall be raised. - -::: {#Table_6.3.7-1 .TH} -Table 6.3.7-1: Entity representations: format + options parameter -::: - -::: TAL -+-----------------+---------------------------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================================+=================+==============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| format | String | 0..1 | When its value is ["normalized"]{.HTML_Code}, a normalized representation of Entities shall be provided as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation), with Attributes returned in the normalized representation as defined in clauses [4.5.2.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), [4.5.3.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship), [4.5.18.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-languageproperty) and [4.5.20.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-vocabproperty). | -| | | | | -| | | | When its value is ["concise"]{.HTML_Code}, a concise lossless representation of Entities shall be provided as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation). with Attributes returned in the concise representation as defined in clauses [4.5.2.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), [4.5.3.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship), [4.5.18.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-languageproperty) and [4.5.20.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-vocabproperty). In this case the [Context Broker]{.HTML_Keyboard} will return data in the most concise lossless representation possible, for example removing all Attribute *type* members. | -| | | | | -| | | | When its value is ["simplified"]{.HTML_Code} (or its synonym ["keyValues"]{.HTML_Code}). a simplified representation of Entities shall be provided as defined by [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation). | -| | | | | -| | | | If the Accept Header is set to ["application/geo+json"]{.HTML_Code} the response will be in simplified GeoJSON format as defined by [clause 4.5.17](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-entities). | -+-----------------+---------------------------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| options | Comma separated list of strings | 0..1 | An alternative mechanism to include the *format* parameter. **Deprecated** | -| | | | | -| | | | When its value includes the keyword ["normalized"]{.HTML_Code}, a normalized representation of Entities shall be provided as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation), with Attributes returned in the normalized representation as defined in clauses [4.5.2.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), [4.5.3.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship), [4.5.18.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-languageproperty) and [4.5.20.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-vocabproperty). | -| | | | | -| | | | When its value includes the keyword ["concise"]{.HTML_Code}, a concise lossless representation of Entities shall be provided as defined by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation). with Attributes returned in the concise representation as defined in clauses [4.5.2.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), [4.5.3.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship), [4.5.18.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-languageproperty) and [4.5.20.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-vocabproperty). In this case the [Context Broker]{.HTML_Keyboard} will return data in the most concise lossless representation possible, for example removing all Attribute *type* members. | -| | | | | -| | | | When its value includes the keyword ["simplified"]{.HTML_Code} (or its synonym ["keyValues"]{.HTML_Code}). a simplified representation of Entities shall be provided as defined by [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation). | -| | | | | -| | | | If the Accept Header is set to ["application/geo+json"]{.HTML_Code} the response will be in simplified GeoJSON format as defined by [clause 4.5.17](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-entities). | -+-----------------+---------------------------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.3.8 Notification behaviour {#tabnotification-behaviour-2 number="11.3.8"} - -In the HTTP binding a notification that is triggered by a subscription shall be sent by issuing an HTTP POST request targeted to the value of *notification.endpoint.uri* member of the subscription structure (defined by clauses [5.2.12](10-tabapi-operation-definition.md#tabsubscription), [5.2.14](10-tabapi-operation-definition.md#tabnotificationparams) and [5.2.15](10-tabapi-operation-definition.md#tabendpoint)). For the HTTP binding, the protocol part of the endpoint URI is http or https. In case the optional MQTT notification binding [(clause 7](12-tabapi-mqtt-notification-binding.md#tabapi-mqtt-notification-binding)) is supported, the protocol part of the endpoint URI can also be *mqtt* or *mqtts*. The MIME type associated to the POST request shall be ["application/json"]{.HTML_Code} by default. However, this can be changed to ["application/ld+json"]{.HTML_Code}*,* or ["application/geo+json"]{.HTML_Code} by means of the *endpoint.accept* member. - -If the target MIME type is ["application/json"]{.HTML_Code} then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD *\@context* as mandated by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 (to the default JSON-LD *\@context* if none available). - -If the optional array (of *KeyValuePair* type, as defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) *notification.endpoint.receiverInfo* of the subscription is present, then a new custom HTTP header for each member named "key" of the key, value pairs that make up the array shall be generated and included in the HTTP POST's list of headers. The content of each custom header shall be set equal to the content of the corresponding "value" member of the *KeyValuePair*. "Key" and "value" members shall adhere to IETF RFC 7230 [[27]](7-tabreferences.md#27) Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers. - -If the target MIME type is ["application/geo+json"]{.HTML_Code} and the *notification.endpoint.receiverInfo* member contains a key ["Prefer" ]{.HTML_Code}whose value is set to ["body=json"]{.HTML_Code} then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD \@context as mandated by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 (to the default JSON-LD *\@context* if none available). - -If the target MIME type is ["application/geo+json"]{.HTML_Code} and the *notification.endpoint.receiverInfo* contains a key ["Prefer"]{.HTML_Code} whose value is set to ["body=ld+json"]{.HTML_Code} or the ["Prefer"]{.HTML_Code} key is omitted or *notification.endpoint.receiverInfo* does not exist, then the HTTP notification request includes an *\@context* element in the payload body. - -### 6.3.9 Csource Notification behaviour {#tabcsource-notification-behaviour number="11.3.9"} - -In the HTTP binding a csource notification that is triggered by a csource subscription shall be sent by issuing an HTTP POST request targeted to the value of *notification.endpoint.uri* member of the csource subscription structure (defined by clauses [5.2.12](10-tabapi-operation-definition.md#tabsubscription) and [5.2.14](10-tabapi-operation-definition.md#tabnotificationparams)). The MIME type associated to the POST request shall be ["application/json"]{.HTML_Code} by default. However, this can be changed to ["]{.HTML_Code}[application/ld+json]{.HTML_Code}["]{.HTML_Code} by means of the *endpoint.accept* member. - -If the target MIME type is ["application/json"]{.HTML_Code} then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD *\@context* as mandated by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 (to the default JSON-LD *\@context* if none available). - -If the optional array (of *KeyValuePair* type, as defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) *notification.endpoint.receiverInfo* of the subscription is present, then a new custom HTTP Header for each member named "key" of the key, value pairs that make up the array shall be generated and included in the HTTP POST's list of headers. The content of each custom header shall be set equal the content of the corresponding "value" member of the *KeyValuePair*. "Key" and "value" members shall adhere to IETF RFC 7230 [[27]](7-tabreferences.md#27) Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers. - -### 6.3.10 Pagination behaviour {#tabpagination-behaviour-1 number="11.3.10"} - -For HTTP operations corresponding to the operations listed in [clause 4.12](9-tabcontext-information-management-framework.md#tabngsi-ld-pagination) (see [Table 6.2‑1](11-tabapi-http-binding.md#Table_6.2-1) for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in [Table 6.3.10‑1](11-tabapi-http-binding.md#Table_6.3.10-1). - -::: {#Table_6.3.10-1 .TH} -Table 6.3.10-1: Pagination: limit parameter -::: - -::: TAL -+-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+====================================================================================================================================================================================================================================================================+ -| limit | Integer | 0..1 | Only values greater or equal to 0. | -| | | | | -| | | | It defines the limit to the number of NGSI-LD Elements that shall be retrieved at a maximum as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). The value 0 is only allowed in combination with the *count* URI parameter. | -+-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -This clause defines the specific HTTP binding mechanisms that shall be used in conjunction with the behaviours defined by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour). Particularly, to flag the existence of related pages that could be retrieved when dealing with query operations involving pagination, NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header field as mandated by IETF RFC 8288 [[7]](7-tabreferences.md#7), [clause 3](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabdefinition-of-terms-symbols-and-abbreviations), as follows: - -::: B1plus -- The pointers to the next and previous pages (when needed as mandated by [clause 5.5.9](10-tabapi-operation-definition.md#tabpagination-behaviour)) shall be serialized as link-value elements. The content of such link-value(s) shall be: -::: - -::: B2plus -- For the next page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the next page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to ["next"]{.HTML_Code}, registered under the IANA Registry of Link Relation Types [[20]](7-tabreferences.md#20). -- For the previous page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the previous page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to ["prev"]{.HTML_Code}, registered under the IANA Registry of Link Relation Types [[20]](7-tabreferences.md#20). -::: - -::: B1plus -- At least, the "type" Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [[7]](7-tabreferences.md#7), , and its value shall be exactly equal to the media type resulting from the original request made by the NGSI-LD Client (the request that triggered the current pagination iteration). -::: - -::: EX -EXAMPLE: - -If the media type requested originally was ["application/json"]{.HTML_Code} then during the entire pagination iteration the value of the Link Target Attribute "type" shall be ["application/json".]{.HTML_Code} -::: - -If the transparent pagination option as described in [clause 5.5.9.2](10-tabapi-operation-definition.md#tabpagination-option-using-limit-and-offset) is used, the URI-references for the ["next"]{.HTML_Code} and["prev"]{.HTML_Code} link to the next and previous pages respectively should include the *limit* parameter as specified in Table 6.3.10-1 and the *offset* parameter as specified in [Table 6.3.10‑2](11-tabapi-http-binding.md#Table_6.3.10-2), giving the Context Consumer more control, i.e. to adapt the size of the page using *limit* and jump to a desired set of elements in the results using *offset*. - -::: {#Table_6.3.10-2 .TH} -Table 6.3.10-2: Pagination: offset parameter -::: - -::: TAL -+----------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {ondemand_PAR_alignment_CENTER} | {ondemand_PAR_alignment_CENTER} | {ondemand_PAR_alignment_CENTER} | {ondemand_PAR_alignment_CENTER} | -| | | | | -| **[Name]{.ondemand_CHAR_name_Arial_size_9}** | **[Data Type]{.ondemand_CHAR_name_Arial_size_9}** | **[Cardinality]{.ondemand_CHAR_name_Arial_size_9}** | **[Remarks]{.ondemand_CHAR_name_Arial_size_9}** | -+==============================================+===================================================+=====================================================+===========================================================================================================================================================================================================================================================================================================================================+ -| offset | Integer | 0..1 | Only values greater or equal to 0. | -| | | | | -| | | | It defines the offset of the first NGSI-LD Element that shall be retrieved from the beginning of the result set. If offset is set to a value larger than the result set, the offset should be assumed to be equal to the size of the result set, i.e. only the last element of the result set is to be returned if there are any results. | -+----------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -Temporal representation of resources adds an additional dimension to the pagination. Depending on the requested time range, the response will contain multiple instances of the requested Attribute, and therefore an additional pagination mechanism for those temporal representations is required, in order to limit the time range of the response. If no limits are specified, a default limit is enforced, depending on implementation specific configurations. For HTTP operations on [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[Evolution]{.HTML_Keyboard}[of Entities]{.HTML_Keyboard}, implementations shall use the Partial Content Response (206) as specified by IETF RFC 7233 [[31]](7-tabreferences.md#31), [clause 4.1](9-tabcontext-information-management-framework.md#tabintroduction), if the implementation is not able to respond with the full representation at once. In this case, for requests where the parameter *lastN* is present, pagination shall happen "backwards" (from the most recent to the least recent timestamp in the requested time range). For requests without the parameter *lastN*, pagination shall happen "forwards" (from the least recent to the most recent timestamp in the requested time range). - -This is achieved by including the ["Content-Range"]{.HTML_Code} header field with the following contents: - -::: B1plus -- ["unit"]{.HTML_Code} shall be equal to ["DateTime"]{.HTML_Code}; -- ["range-start"]{.HTML_Code} and ["range-end"]{.HTML_Code} shall be of type *DateTime.* They depend on the requested time relationship *timerel* (as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)), as follows: -::: - -::: B2plus -- If the *lastN* parameter is present, pagination shall happen "backwards": -::: - -::: B3plus -- ["range-start"]{.HTML_Code} shall be equal to ["timeAt"]{.HTML_Code} for requests with *timerel=before*, ["endTimeAt"]{.HTML_Code} for requests with *timerel=between*, or the most recent timestamp in the range of the response, for requests with *timerel=after*; -- ["range-end"]{.HTML_Code} shall be equal to the least recent timestamp in the range of the response; -- ["size"]{.HTML_Code} shall be equal to the requested *lastN*. -::: - -::: B2plus -- If the *lastN* parameter is **not** present, pagination shall happen "forwards": -::: - -::: B3plus -- ["range-start"]{.HTML_Code} shall be equal to *timeAt* for requests with *timerel=after* or *timerel=between*, or the least recent timestamp in the range of the response, for requests with *timerel=before*; -- ["range-end"]{.HTML_Code} shall be equal to the most recent timestamp in the range of the response; -- ["size"]{.HTML_Code} shall be equal to *"\*"*. -::: - -### 6.3.11 Including system Attributes {#tabincluding-system-attributes number="11.3.11"} - -For HTTP GET operations performed over the resources /entities/, /subscriptions/, /csourceRegistrations/, /csourceSubscriptions/, /temporal/entities/ and all of its sub-resources, and for HTTP POST operations corresponding to "Query Entities" (see [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) and "Query Temporal Evolutions of Entities" (see [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)), implementations shall support the parameter specified in [Table 6.3.11‑1](11-tabapi-http-binding.md#Table_6.3.11-1). Implementations shall not raise an error if they do not hold system generated temporal attributes. - -::: {#Table_6.3.11-1 .TH} -Table 6.3.11-1: Including system generated temporal attributes: options parameter -::: - -::: TAL -+-----------------+---------------------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================================+=================+===============================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| options | Comma separated list of strings | 0..1 | When its value includes the keyword ["sysAttrs",]{.HTML_Code} a representation of NGSI-LD Elements shall be provided so that the system generated temporal attributes *createdAt*, *modifiedAt* and the system temporal attribute*expiresAt* are included in the response payload body where known. In the case of temporal representations, also the system generated temporal attribute *deletedAt* is included, if the NGSI-LD Element has been deleted. | -+-----------------+---------------------------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.3.12 Simplified or aggregated temporal representation of Entities {#tabsimplified-or-aggregated-temporal-representation-of-entities number="11.3.12"} - -For HTTP GET and POST operations corresponding to "Retrieve Temporal Evolution of an Entity" (see [clause 5.7.3](10-tabapi-operation-definition.md#tabretrieve-temporal-evolution-of-an-entity)) and "Query Temporal Evolution of Entities" (see [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)), implementations shall support the parameter specified in [Table 6.3.12‑1](11-tabapi-http-binding.md#Table_6.3.12-1). - -::: {#Table_6.3.12-1 .TH} -Table 6.3.12-1: Temporal Entity representations: format + options parameters -::: - -::: TAL -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================================+=================+===================================================================================================================================================================================================================================================================================+ -| format | String | 0..1 | It shall be one of: ["temporalValues"]{.HTML_Code}, ["aggregatedValues"]{.HTML_Code}. | -| | | | | -| | | | When its value is ["temporalValues"]{.HTML_Code}, a simplified temporal representation of entities shall be provided as defined by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). | -| | | | | -| | | | When its value is ["aggregatedValues"]{.HTML_Code}, an aggregated temporal representation of entities shall be provided as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). | -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| options | Comma separated list of strings | 0..1 | An alternative mechanism to include the *format* parameter. **Deprecated** | -| | | | | -| | | | When its value includes the keyword ["temporalValues"]{.HTML_Code}, a simplified temporal representation of entities shall be provided as defined by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). | -| | | | | -| | | | When its value includes the keyword ["aggregatedValues"]{.HTML_Code}, an aggregated temporal representation of entities shall be provided as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). | -| | | | | -| | | | Only one of the two keywords can be present in the values of the parameter. | -| | | | | -| | | | If both *format* and *options* are present, the value of the *format* parameter shall take precedence. | -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.3.13 Counting number of results {#tabcounting-number-of-results number="11.3.13"} - -This clause implements the behaviour described in [clause 4.13](9-tabcontext-information-management-framework.md#tabcounting-the-number-of-results), in case of HTTP binding. - -For HTTP operations corresponding to the operations listed in [clause 4.12](9-tabcontext-information-management-framework.md#tabngsi-ld-pagination) (see [Table 6.2‑1](11-tabapi-http-binding.md#Table_6.2-1) for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in [Table 6.3.13‑1](11-tabapi-http-binding.md#Table_6.3.13-1). - -::: {#Table_6.3.13-1 .TH} -Table 6.3.13-1: Counting number of results: count parameter -::: - -::: TAL -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+==================================================================================================================================================================================================================================================================+ -| count | Boolean | 0..1 | If *true*, then a special HTTP header (NGSILD-Results-Count) is set in the response. Regardless of how many entities are actually returned (maybe due to the *limit* URI parameter), the total number of matching results (e.g. number of Entities) is returned. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -This clause defines the specific HTTP binding mechanisms that can be useful to plan the *limit* and *offset* URI parameters for pagination, thus allowing to convey an overview of the number of entities in a system. - -To get only the count itself, and no entities, the URI parameter *limit* may have the value ["0"]{.HTML_Code}, and an empty array shall be returned as payload body. - -Setting the URI parameter *limit* to zero without including the *count* URI parameter will result in a 400 *BadRequest* error. - -### 6.3.14 Tenant specification {#tabtenant-specification number="11.3.14"} - -If the system implementing the NGSI-LD API supports multi-tenancy as described in [clause 4.14](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants) and [clause 5.5.10](10-tabapi-operation-definition.md#tabmulti-tenant-behaviour), the [Tenant]{.HTML_Keyboard}, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header ["NGSILD-]{.HTML_Code}[Tenant]{.HTML_Code}["]{.HTML_Code}, whose value is the String identifying the [Tenant]{.HTML_Keyboard}. In case the target [Tenant]{.HTML_Keyboard} is the default [Tenant]{.HTML_Keyboard}, the HTTP header is omitted. If the HTTP header ["NGSILD-]{.HTML_Code}[Tenant]{.HTML_Code}["]{.HTML_Code} is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an ["NGSILD-]{.HTML_Code}[Tenant]{.HTML_Code}["]{.HTML_Code} HTTP header [(clause 6.3.8](11-tabapi-http-binding.md#tabnotification-behaviour-2)). - -### 6.3.15 GeoJSON representation of spatially bound entities {#tabgeojson-representation-of-spatially-bound-entities number="11.3.15"} - -For HTTP GET and POST operations corresponding to "Retrieve Entity" (see [clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)) and "Query Entities" (see [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)), if the GeoJSON Accept header (["application/geo+json"]{.HTML_Code}) is present, implementations shall render the entities of the response in the GeoJSON format, as described in [clause 5.2.29](10-tabapi-operation-definition.md#tabfeature). - -For GeoJSON representations, a *GeoProperty* may be selected as the geolocation to be used as the geometry within the GeoJSON payload. If no *geometryProperty* parameter is specified, then the *location* *GeoProperty* of the Entity is used. - -::: {#Table_6.3.15-1 .TH} -Table 6.3.15-1: Selecting a geometry -::: - -::: TAL -+------------------+-----------------+-----------------+-----------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+=================+=================+=====================================================+ -| geometryProperty | String | 0..1 | If not present, ["location"]{.HTML_Code} is used. | -+------------------+-----------------+-----------------+-----------------------------------------------------+ -::: - -### 6.3.16 Expiration time for cached \@contexts {#tabexpiration-time-for-cached-contexts number="11.3.16"} - -Implementations shall comply with the Expires header field (section 5.3 of IETF RFC 7234 [[30]](7-tabreferences.md#30)) or a max-age or s-maxage response directive of Cache-Control header field (section 5.2.2 of IETF RFC 7234 [[30]](7-tabreferences.md#30)) that may be present in the downloaded *\@context*. This means that implementations shall periodically invalidate the ["Cached"]{.HTML_Code} *\@contexts* according to the headers mentioned above. Since origin servers do not always provide explicit expiration times, implementations should assign a heuristic (for instance according to IETF RFC 7234 [[30]](7-tabreferences.md#30) section 4.2.2) expiration time when an explicit time is not specified. - -### 6.3.17 Distributed Operations Caching and Timeout Behaviour {#tabdistributed-operations-caching-and-timeout-behaviour number="11.3.17"} - -The caching of response data received from forwarded HTTP GET requests is optionally supported by [Context Brokers]{.HTML_Keyboard}. For HTTP GET operations performed over the resources /entities and /entities/{entity-id}, where a [Context Source Registration]{.HTML_Keyboard} matches the request and a previous forwarded response has been cached and a subsequent request occurs before the [Context Source Registration]{.HTML_Keyboard} *cacheDuration* (as defined in [Table 5.2.34‑1](10-tabapi-operation-definition.md#Table_5.2.34-1)) has been reached, the result may incorporate data cached from a previous response[.]{.ondemand_CHAR_size_12_color_000000} To indicate that data from a cache has been included in the response, the HTTP header ["NGSILD-Warning"]{.HTML_Code} shall be included. The value shall match the IANA Warning Code [[32]](7-tabreferences.md#32) 110 - Response is Stale. - -["NGSILD-Warning"]{.HTML_Code} HTTP headers shall also be used to indicate instances of abnormal behaviour for distributed HTTP GET operations performed over the resources /entities and /entities/{entity-id}. - -::: {#Table_6.3.17-1 .TH} -Table 6.3.17-1: NGSI-LD Warning Codes -::: - -::: TAL -+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| IANA Warning Code | Remarks | -+========================================+================================================================================================================================================================================================================================================+ -| 110 - Response is Stale | No request was made to a specified registration endpoint - data from a cached value has been reused and it has been incorporated into the response. | -+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 111 - Revalidation Failed | Although data was received from the registration endpoint within the specified timeout period, the payload of the response was invalid. This could occur if the payload was corrupted or a non-NGSI payload was received. | -+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 199 - Miscellaneous Warning | No response was received from the registration endpoint within the specified timeout period or a registration loop has been detected. | -+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 299 - Miscellaneous Persistent Warning | An error response (such as **403 - Forbidden**) was received from the registration endpoint within the specified timeout period. This could occur if the [Context Broker]{.HTML_Keyboard} has insufficient access rights to retrieve the data. | -+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -For distributed HTTP GET operations, registered context sources should always respond with a valid NGSI-LD payload. The [Context Broker]{.HTML_Keyboard} shall successfully parse this data and invalid non-NGSI-LD payloads shall be rejected and not incorporated into the overall response. It should be noted that a registration endpoint responding with no data and the HTTP status code **404 - Not Found** should not be considered as abnormal behaviour for distributed operations. - -For all other operations, which correspond to HTTP Unsafe methods, the error response should be as informative as possible. - -In the case of an **exclusive** or **redirect** registration, where all of the data is held outside of the [Context Broker]{.HTML_Keyboard} and held in a single registered source, the following errors shall be returned: - -::: B1plus -- 508 Loop Detected - if the single registered source and tenant is registered to redirect back on to the [Context Broker.]{.HTML_Keyboard} -- 504 Gateway Timeout - if the single registered source fails to respond in time. -- 404 Not Found - if resources not found within the single registered source. -- 502 Bad Gateway - if the single forwarded request fails for any other reason such as the [Context Broker]{.HTML_Keyboard} itself having insufficient access rights. -::: - -In the case of an **inclusive** or **redirect** registration, where an entity is distributed over multiple equally valid endpoints, but when updating the state of the distributed entity, an error response is returned from one or more registered sources: - -::: B1plus -- 207 Multi Status. -::: - -In the case of an **auxiliary** registration HTTP unsafe methods are not supported. - -Whenever failures or timeouts occur, [Context Brokers]{.HTML_Keyboard} may optionally decline to make subsequent requests to the same registration endpoint until the [cooldown period (as defined in ]{.ondemand_CHAR_color_000000}[Table]{.ondemand_CHAR_color_000000}5.2.9-1[) has been reached.]{.ondemand_CHAR_color_000000} - -### 6.3.18 Limiting Distributed Operations {#tablimiting-distributed-operations number="11.3.18"} - -The parameter described in this clause limits the execution of an operation to a local *Context Source* or *Context Broker* [(clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). It amends the matching [Context Source Registrations]{.HTML_Keyboard} behaviour as described in [clause 5.12](10-tabapi-operation-definition.md#tabmatching-context-source-registrations), in the case of the HTTP binding in order to avoid cascading distributed operations (see [clause 4.3.6.4](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations)). For all operations the resources /entities/, /types/, /attributes/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ (and their respective child resources) implementations shall support the HTTP query parameter specified in [Table 6.3.18‑1](11-tabapi-http-binding.md#Table_6.3.18-1). The Registry API operations are always local and thus are not included here. Operations on a Snapshot (see [clause 5.5.15](10-tabapi-operation-definition.md#tabsnapshot-behaviour)) are always implicitly local scope, overriding setting the *local* parameter to *false*, i.e. such a setting is to be ignored by implementations. - -::: {#Table_6.3.18-1 .TH} -Table 6.3.18-1: Limiting distributed operations: local parameter -::: - -::: TAL -+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===========================================================================================================================================================================================================================================================================+ -| local | Boolean | 0..1 | If *local=true* then no [Context Source Registrations]{.HTML_Keyboard} shall be considered as matching to avoid cascading distributed operations (see [clause 4.3.6.4](9-tabcontext-information-management-framework.md#tablimiting-cascading-distributed-operations)). | -+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -Furthermore, to avoid infinite loops, for all operations, the resources /entities/, /types/, /attributes/, /subscriptions/, /csourceSubscriptions/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ implementations shall fully support the HTTP Via Header (IETF RFC 7230 [[27]](7-tabreferences.md#27)) as specified in [Table 6.3.18‑2](11-tabapi-http-binding.md#Table_6.3.18-2). Any[Context Broker]{.HTML_Keyboard} implementation passing a distributed operation request onward to another [Context Source]{.HTML_Keyboard} shall send an additional field value on the Via header field using its own unique [Context Source]{.HTML_Keyboard} *hostAlias* (see [clause 5.2.40](10-tabapi-operation-definition.md#tabcontext-source-identity)) as the pseudonym. - -::: {#Table_6.3.18-2 .TH} -Table 6.3.18-2: Request Headers -::: - -::: TAL -+-----------------+----------------------------------------------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+======================================================================+=================+===============================================================================================================================================+ -| Via | String as defined in IETF RFC 7230 [[27]](7-tabreferences.md#27) | 0..1 | If present, the listing of previously encountered [Context Sources]{.HTML_Keyboard} supplied is used when determining matching registrations. | -+-----------------+----------------------------------------------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.3.19 Extra information to provide when contacting Context Source {#tabextra-information-to-provide-when-contacting-context-source-1 number="11.3.19"} - -As specified in clauses [4.3.6.5](9-tabcontext-information-management-framework.md#tabextra-information-to-provide-when-contacting-context-source) and [4.3.6.6](9-tabcontext-information-management-framework.md#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source), extra information to be provided when contacting a [Context Source]{.HTML_Keyboard} can be specified in the optional array (of *KeyValuePair* type, as defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) *contextSourceInfo* of the CSourceRegistration. - -In the HTTP binding, if the ["jsonldContext"]{.HTML_Code} key is present, the URL value is placed in an HTTP Link Header as described by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 and, whenever a payload body is present in the request, the HTTP Content-Type Header is set to ["application/json"]{.HTML_Code}. For all other keys, a new custom HTTP header is added for each member named "key" of the key-value pairs that make up the array shall be generated and included in the HTTP list of headers. The content of each custom header shall be set equal to the content of the corresponding "value" member of the *KeyValuePair*, unless the special value ["urn:ngsi-ld:request"]{.HTML_Code} has been set, in which case the value is to be taken from the triggering request, if present there. "Key" and "value" members shall adhere to IETF RFC 7230 [[27]](7-tabreferences.md#27) Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers. - -Headers derived from other elements of the CSourceRegistration, e.g. ["]{.HTML_Code}[NGSILD]{.HTML_Code}[-]{.HTML_Code}[Tenant]{.HTML_Code}["]{.HTML_Code}, take precedence and cannot be overridden using *contextSourceInfo*. The same applies for headers generally set by HTTP itself, e.g. Content-length. - -### 6.3.20 Invalid parameters {#tabinvalid-parameters number="11.3.20"} - -If an HTTP request for an operation contains parameters that are incompatible with the operation, or it contains values of the *options* parameter that are not supported by the operation, an HTTP error response of type *InvalidRequest* should be returned. - -### 6.3.21 Optional profile information regarding versioning and datatype conformance {#taboptional-profile-information-regarding-versioning-and-datatype-conformance number="11.3.21"} - -In the HTTP Binding, if an HTTP - -Link header with a - -*profile* - -parameter - -in accordance with IETF RFC 6906 [[33]](7-tabreferences.md#33), is found set to [ then implementations that are only partially capable of interpreting the datatypes conformant to the supplied NGSI-LD version may use this information to allow the payload to be accepted within the constraints of the current implementation (see [clause 5.5.4](10-tabapi-operation-definition.md#tabgeneral-ngsi-ld-validation)) through amending the payload body and applying the fallbacks defined within [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). - -### 6.3.22 Snapshot specification {#tabsnapshot-specification number="11.3.22"} - -If the system implementing the NGSI-LD API supports Snapshots as described in [clause 4.3.7](9-tabcontext-information-management-framework.md#tabsnapshots) and [clause 5.5.15](10-tabapi-operation-definition.md#tabsnapshot-behaviour), the [Snapshot]{.HTML_Keyboard}, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header ["NGSILD-Snapshot"]{.HTML_Code}, whose value is the identifier of the Snapshot. If the HTTP header ["NGSILD-Snapshot"]{.HTML_Code} is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an ["NGSILD-Snapshot"]{.HTML_Code} HTTP header [(clause 6.3.8](11-tabapi-http-binding.md#tabnotification-behaviour-2)). - -## 6.4 Resource: entities/ {#tabresource-entities number="11.4"} - -### 6.4.1 Description {#tabdescription-62 number="11.4.1"} - -This resource represents the entities known to an NGSI-LD system. - -### 6.4.2 Resource definition {#tabresource-definition number="11.4.2"} - -Resource URI: - -::: B1plus -- /entities/ -::: - -### 6.4.3 Resource methods {#tabresource-methods number="11.4.3"} - -#### 6.4.3.1 POST {#tabpost number="11.4.3.1"} - -This method is bound to the operation "Create Entity" and shall exhibit the behaviour defined by [clause 5.6.1](10-tabapi-operation-definition.md#tabcreate-entity), taking the entity to be created from the HTTP request payload body. [Figure 6.4.3.1‑1](11-tabapi-http-binding.md#Figure_6.4.3.1-1) shows the Create Entity interaction and [Table 6.4.3.1‑1](11-tabapi-http-binding.md#Table_6.4.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image79.png){style="width:3.94444in;height:2.56944in"} -::: - -::: {#Figure_6.4.3.1-1 .TF} -Figure 6.4.3.1-1: Create Entity interaction -::: - -::: {#Table_6.4.3.1-1 .TH} -Table 6.4.3.1-1: Create Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity | 1 | Payload body in the request contains a JSON-LD object which represents the entity that is to be created. | -+===============+======================================================================+=============+======================================================+==============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created entity. | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created entity. | -| | | | | | -| | | | | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* member should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that the entity or an exclusive or redirect registration defining the entity already exists, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 422 Unprocessable Entity | It is used to indicate that the operation is not available, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.4.3.2 GET {#tabget number="11.4.3.2"} - -This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities), providing entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Query Entities" operations via POST is defined in [clause 6.23](11-tabapi-http-binding.md#tabresource-entityoperationsquery). [Figure 6.4.3.2‑1](11-tabapi-http-binding.md#Figure_6.4.3.2-1) shows the query entities interaction. - -::: FL -![](./media/image80.png){style="width:4.18056in;height:4.83333in"} -::: - -::: {#Figure_6.4.3.2-1 .TF} -Figure 6.4.3.2-1: Query Entities interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.4.3.2‑1](11-tabapi-http-binding.md#Table_6.4.3.2-1), the request headers that shall be supported by implementations are those defined in [Table 6.4.3.2‑2](11-tabapi-http-binding.md#Table_6.4.3.2-2) and [Table 6.4.3.2‑3](11-tabapi-http-binding.md#Table_6.4.3.2-3) describes the request body and possible responses. - -::: {#Table_6.4.3.2-1 .TH} -Table 6.4.3.2-1: Query Entities URL parameters -::: - -::: TAL -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+===================+====================================================================+===================================================================================================================================================================================================================================================================================================+=============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| attrs | Comma separated list of strings | 0..1 | A synonym for a combination of the *pick* and*q* members. **Deprecated** | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entities and also included in the response, i.e. only Entities that contain at least one of the Attributes in *attrs* are to be included in the response, and only the Attributes listed in *attrs* are to be included in each of the Entities of the response. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| collation | String | 0..1 | An ICU collation (see IETF RFC 6067 [[36]](7-tabreferences.md#36)), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| containedBy | Comma separated list of URIs | 0..1 | List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if *joinLevel* is present. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| coordinates | String | 0..1 | Coordinates serialized as a string as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be one if *geometry* or *georel* are present. | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | 0..1 | [Context Source]{.HTML_Keyboard} filter as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | Comma separated list of strings | 0..1 | Shall be valid URIs, "@none" for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMap | Boolean | 0..1 | If *true*, the location of the EntityMap used in the operation is returned in the response. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMapLifetime | String | 0..1 | Suggested duration, represented in ISO 8601 [[17]](7-tabreferences.md#17) format [[17]](7-tabreferences.md#17), for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if *entityMap* is set to *true*. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expandValues | Comma separated list of strings | 0..1 | Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied *\@context* prior to executing a query. It is part of query. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | 0..1 | Geometry as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *georel* or *coordinates* are present. At least one among: *type*, *attrs*, *q*, or *geometry* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometryProperty | String | 0..1 | It represents a Property name. | -| | | | | -| | | | In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the top-level *geometry* field. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoproperty | String | 0..1 | It represents the name of the *Property* that contains the geospatial data that will be used to resolve the geoquery. By default, will be *location* (see [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties)). | -| | | | | -| | | It shall be ignored unless a *geoquery* is present. | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| georel | String | 0..1 | Geo relationship as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *geometry* or *coordinates* are present. | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id | Comma separated list of strings | 0..1 | Each String shall be a valid URI. List of entity ids to be retrieved. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| idPattern | Regular expression as defined by [[11]](7-tabreferences.md#11) | 0..1 | Regular expression that shall be matched by entity ids. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| join | String | 0..1 | The type of [Linked Entity]{.HTML_Keyboard} retrieval to apply (see [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval)). Allowed values: ["flat"]{.HTML_Code}, ["inline","@none"]{.HTML_Code} . | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| joinLevel | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML_Keyboard} retrieval to apply. | -| | | | | -| | | | Only applicable if *join* parameter is present. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| jsonKeys | Comma separated list of strings | 0..1 | Each String is an Attribute (Property or Relationship) name. | -| | | | | -| | | | Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the preferred natural language of the response. | -| | | | | -| | | | It is used to reduce *languageMaps* to a string or string array property in a single preferred language. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). | -| | | | | -| | | | When defined, the listed Entity members are removed from each Entity within the payload. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| orderBy | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name) appended with an optional sorting style (["asc"]{.HTML_Code}, ["desc"]{.HTML_Code}, ["dist-asc"]{.HTML_Code}, ["dist-desc") ]{.HTML_Code}as per [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering). When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| orderFrom | String | 0..1 | Coordinates of a Geometry serialized as a string as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of Entity ordering. | -| | | | | -| | | It shall be one if *orderBy* uses order by distance | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| orderGeometry | String | 0..1 | A Geometry type (with the exception of *GeometryCollection)* as defined by the GeoJSON specification (IETF RFC 7946 [[8]](7-tabreferences.md#8)). It is part of Entity ordering. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). | -| | | | | -| | | | When defined, every Entity within the payload body is reduced down to only contain the listed Entity members. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | 0..1 | Query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | 0..1 | Scope query (see [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)). | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| splitEntities | Boolean | 0..1 | If *true* it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If *false* it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. | -| | | | | -| | | | The parameter does not apply in case *local*is *true*. | -| | | | | -| | | | The default value should be decided by implementation; it should be configurable. | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | [0..1]{.ondemand_CHAR_name_Arial_size_9} | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). ["\*"]{.HTML_Code} is also allowed as a value and *local* is implicitly set to *true* and shall not be explicitly set to*false*. | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+-------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.4.3.2-2 .TH} -Table 6.4.3.2-2: Query Entities request Headers -::: - -::: TAL -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+=================+=================+=============================================================================================================================================================================================================+ -| NGSILD-EntityMap | URI | 0..1 | If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query operation is returned in the response. | -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.4.3.2-3 .TH} -Table 6.4.3.2-3: Query Entities request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=========================================================+============================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | 200 OK | A response body containing the query result as a list of entities, unless the Accept Header indicates that the Entities are to be rendered as GeoJSON. | -| | | | | | -| | Entity[] | 1 | 201 Created (in case an EntityMap has been (re)created) | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | {TAH} | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | -| | | | | | -| | Entity[] | 1 | 203 Non-Authoritative Information | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoJSON FeatureCollection | 1 | 200 OK | If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned. | -| | | | | | -| | | | 201 Created (in case an EntityMap has been (re)created) | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 501 Not Implemented | It is used by Registered [Context Sources]{.HTML_Keyboard} to indicate that the data format of the request is unsupported see [clause 6.3.7](11-tabapi-http-binding.md#tabrepresentation-of-entities). | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.4.3.3 DELETE {#tabdelete number="11.4.3.3"} - -This method is associated to the operation "Purge Entities" and shall exhibit the behaviour defined by [clause 5.6.21](10-tabapi-operation-definition.md#tabpurge-entities), providing entities as part of the HTTP response payload body. [Figure 6.4.3.3‑1](11-tabapi-http-binding.md#Figure_6.4.3.3-1) shows the query entities interaction. - -::: FL -![](./media/image81.png){style="width:3.93056in;height:2.52778in"} -::: - -::: {#Figure_6.4.3.3-1 .TF} -Figure 6.4.3.3-1: Purge Entities interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.4.3.3‑1](11-tabapi-http-binding.md#Table_6.4.3.3-1), the request headers that shall be supported by implementations are those defined in [Table 6.4.3.3‑2](11-tabapi-http-binding.md#Table_6.4.3.3-2) and [Table 6.4.3.3‑3](11-tabapi-http-binding.md#Table_6.4.3.3-3) describes the request body and possible responses. - -::: {#Table_6.4.3.3-1 .TH} -Table 6.4.3.3-1: Purge Entities URL parameters -::: - -::: TAL -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+====================================================================+===================================================================================================================================================================================================================================================================================================+==================================================================================================================================================================================================================================================================================+ -| coordinates | String | 0..1 | Coordinates serialized as a string as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be one if *geometry* or *georel* are present. | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | 0..1 | [Context Source]{.HTML_Keyboard} filter as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| drop | Comma separated list of strings | 0..1 | Each String is an Attribute name. | -| | | | | -| | | | When defined, every Entity within the payload body is reduced to not contain the listed Entity members. | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | 0..1 | Geometry as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *georel* or *coordinates* are present. At least one among: *type*, *attrs*, *q*, or *geometry* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometryProperty | String | 0..1 | It represents a Property name. | -| | | | | -| | | | In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the top-level *geometry* field. | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoproperty | String | 0..1 | It represents the name of the *Property* that contains the geospatial data that will be used to resolve the geoquery. By default, will be *location* (see [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties)). | -| | | | | -| | | It shall be ignored unless a *geoquery* is present. | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| georel | String | 0..1 | Geo relationship as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *geometry* or *coordinates* are present. | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id | Comma separated list of strings | 0..1 | Each String shall be a valid URI. List of entity ids to be retrieved. | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| idPattern | Regular expression as defined by [[11]](7-tabreferences.md#11) | 0..1 | Regular expression that shall be matched by entity ids. | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| keep | Comma separated list of strings | 0..1 | Each String is an Attribute name. | -| | | | | -| | | | When defined, every Entity within the payload body is reduced down to only contain the listed Entity members. | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | 0..1 | Query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | 0..1 | Scope query (see [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)). | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | [0..1]{.ondemand_CHAR_name_Arial_size_9} | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). ["\*"]{.HTML_Code} is also allowed as a value and *local* is implicitly set to *true* and shall not be explicitly set to*false*. | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.4.3.3-2 .TH} -Table 6.4.3.3-2: Purge Entities request Headers -::: - -::: TAL -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+=================+=================+=============================================================================================================================================================================================================+ -| NGSILD-EntityMap | URI | 0..1 | If present, the EntityMap supplied is used for determining the set of Entities requested during the purge operation. The location of the EntityMap used in the purge operation is returned in the response. | -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.4.3.3-3 .TH} -Table 6.4.3.3-3: Purge Entities request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+==================+==============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.5 Resource: entities/{entityId} {#tabresource-entitiesentityid number="11.5"} - -### 6.5.1 Description {#tabdescription-63 number="11.5.1"} - -This resource represents an entity known to an NGSI-LD system. - -### 6.5.2 Resource definition {#tabresource-definition-1 number="11.5.2"} - -Resource URI: - -::: B1plus -- /entities/{entityId} -::: - -Resource URI variables for this resource are defined in [Table 6.5.2‑1](11-tabapi-http-binding.md#Table_6.5.2-1). - -::: {#Table_6.5.2-1 .TH} -Table 6.5.2-1: URI variables -::: - -::: TAL -+-----------------------------------+----------------------------------------+ -| Name | Definition | -+===================================+========================================+ -| entityId | Id (URI) of the entity to be retrieved | -+-----------------------------------+----------------------------------------+ -::: - -### 6.5.3 Resource methods {#tabresource-methods-1 number="11.5.3"} - -#### 6.5.3.1 GET {#tabget-1 number="11.5.3.1"} - -This method is associated to the operation "Retrieve Entity" and shall exhibit the behaviour defined by [clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity). The Entity identifier is the value of the resource URI variable "entityId". [Figure 6.5.3.1‑1](11-tabapi-http-binding.md#Figure_6.5.3.1-1) shows the retrieve entity interaction. - -::: FL -![](./media/image82.png){style="width:3.41667in;height:3.29167in"} -::: - -::: {#Figure_6.5.3.1-1 .TF} -Figure 6.5.3.1-1: Retrieve Entity interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.5.3.1‑1](11-tabapi-http-binding.md#Table_6.5.3.1-1), the request headers that shall be supported by implementations are those defined in [Table 6.5.3.1‑2](11-tabapi-http-binding.md#Table_6.5.3.1-2) and [Table 6.5.3.1‑3](11-tabapi-http-binding.md#Table_6.5.3.1-3) describes the request body and possible responses. - -::: {#Table_6.5.3.1-1 .TH} -Table 6.5.3.1-1: Retrieve Entity URL parameters -::: - -::: TAL -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+===================+=================================+=================+=======================================================================================================================================================================================================================================================================================================================================================================+ -| attrs | Comma separated list of strings | 0..1 | A synonym for the *pick* parameter, except that *id, type, scope* are not allowed. **Deprecated** | -| | | | | -| | | | Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entity and included in the response. If the Entity does not have any of the Attributes in *attrs*, then a *404 Not Found* shall be retrieved. If *attrs* is not specified, no matching is performed and all Attributes related to the Entity shall be retrieved. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| containedBy | Comma separated list of URIs | 0..1 | List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if *joinLevel* is present. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | Comma separated list of strings | 0..1 | Shall be valid URIs, ["@none"]{.HTML_Code} for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMap | Boolean | 0..1 | If *true*, the location of the EntityMap used in the operation is returned in the response. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMapLifetime | String | 0..1 | Suggested duration, represented in ISO 8601 [[17]](7-tabreferences.md#17) format, for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if *entityMap* is set to *true*. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometryProperty | String | 0..1 | It represents a *GeoProperty* name. | -| | | | | -| | | | In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the "geometry" element. By default, it shall be *location*. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| join | String | 0..1 | The type of [Linked Entity]{.HTML_Keyboard} retrieval to apply (see [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval)). Allowed values: ["flat"]{.HTML_Code}, ["inline"]{.HTML_Code}, ["@none"]{.HTML_Code} . | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| joinLevel | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML_Keyboard} retrieval to apply. Default is 1 | -| | | | | -| | | | Only applicable if *join* parameter is: ["flat"]{.HTML_Code} or ["inline"]{.HTML_Code}. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the preferred natural language of the response. | -| | | | | -| | | | It is used to reduce *languageMaps* to a string or string array property in a single preferred language. | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). When defined, the listed Entity members are removed from the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval). | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). When defined, the Entity is reduced down to only contain the listed Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval). | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-------------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.5.3.1-2 .TH} -Table 6.5.3.1-2: Retrieve Entity request Headers -::: - -::: TAL -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+=================+=================+===============================================================================================================================================================================================================================+ -| NGSILD-EntityMap | URI | 0..1 | If present, the EntityMap supplied is used for determining the extent of the Entity data requested during the retrieval operation. The location of the EntityMap used in the retrieval operation is returned in the response. | -+------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.5.3.1-3 .TH} -Table 6.5.3.1-3: Retrieve Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+===================================+============================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | {TAH} | A response body containing the JSON-LD representation of the target entity which consists only of the selected Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON. | -| | | | | | -| | Entity | 1 | 200 OK | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | {TAH} | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | -| | | | | | -| | Entity | 1 | 203 Non-Authoritative Information | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoJSON Feature | 1 | 200 OK | If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON *Feature* is returned. | -| | | | | | -| | | | | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 501 Not Implemented | It is used by Registered [Context Sources]{.HTML_Keyboard} to indicate that the data format of the request is unsupported see [clause 6.3.7](11-tabapi-http-binding.md#tabrepresentation-of-entities). | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.5.3.2 DELETE {#tabdelete-1 number="11.5.3.2"} - -This method is associated to the operation "Delete Entity" and shall exhibit the behaviour defined by [clause 5.6.6](10-tabapi-operation-definition.md#tabdelete-entity). The Entity identifier is the value of the resource URI variable "entityId". [Figure 6.5.3.2‑1](11-tabapi-http-binding.md#Figure_6.5.3.2-1) shows the delete entity interaction. - -::: FL -![](./media/image83.png){style="width:3.91667in;height:2.18056in"} -::: - -::: {#Figure_6.5.3.2-1 .TF} -Figure 6.5.3.2-1: Delete Entity interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.5.3.2‑1](11-tabapi-http-binding.md#Table_6.5.3.2-1) and [Table 6.5.3.2‑2](11-tabapi-http-binding.md#Table_6.5.3.2-2) describes the request body and possible responses. - -::: {#Table_6.5.3.2-1 .TH} -Table 6.5.3.2-1: Delete Entity URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===============================================================================================================================================+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.5.3.2-2 .TH} -Table 6.5.3.2-2: Delete Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+==================+==============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.5.3.3 PUT {#tabput number="11.5.3.3"} - -This method is bound to the "Replace Entity" operation and shall exhibit the behaviour defined by [clause 5.6.18](10-tabapi-operation-definition.md#tabreplace-entity). The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. [Figure 6.5.3.3‑1](11-tabapi-http-binding.md#Figure_6.5.3.3-1) shows the Replace Entity interaction. - -::: FL -![](./media/image84.png){style="width:3.94444in;height:2.56944in"} -::: - -::: {#Figure_6.5.3.3-1 .TF} -Figure 6.5.3.3-1: Replace Entity interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.5.3.3‑1](11-tabapi-http-binding.md#Table_6.5.3.3-1) and [Table 6.5.3.3‑2](11-tabapi-http-binding.md#Table_6.5.3.3-2) describes the request body and possible responses. - -::: {#Table_6.5.3.3-1 .TH} -Table 6.5.3.3-1: Replace Entity URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===============================================================================================================================================+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.5.3.3-2 .TH} -Table 6.5.3.3-2: Replace Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity Fragment | 1 | Entity Fragment containing a complete representation of the Entity to be replaced. | -+===============+======================================================================+=============+===========================================+==============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No content | The entity was replaced successfully. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.5.3.4 PATCH {#tabpatch number="11.5.3.4"} - -This method is bound to the "Merge Entity" operation and shall exhibit the behaviour defined by [clause 5.6.17](10-tabapi-operation-definition.md#tabmerge-entity). The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. [Figure 6.5.3.4‑1](11-tabapi-http-binding.md#Figure_6.5.3.4-1) shows the Merge Entity interaction. - -::: FL -![](./media/image85.png){style="width:3.94444in;height:2.56944in"} -::: - -::: {#Figure_6.5.3.4-1 .TF} -Figure 6.5.3.4-1: Merge Entity interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.5.3.4‑1](11-tabapi-http-binding.md#Table_6.5.3.4-1) and [Table 6.5.3.4‑2](11-tabapi-http-binding.md#Table_6.5.3.4-2) describes the request body and possible responses. - -::: {#Table_6.5.3.4-1 .TH} -Table 6.5.3.4-1: Merge Entity URL parameters -::: - -::: TAL -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================================+=================+=============================================================================================================================================================================================================================================================================================================+ -| format | String | 0..1 | It shall be one of: ["simplified"]{.HTML_Code} (or its synonym ["keyValues"]{.HTML_Code}). Where present it indicates that a simplified representation of Entities has been provided as defined by [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation). | -| | | | | -| | | | In this case, when a merge operation applies to an existing Attribute the *type* field of the Attribute shall remain unchanged (any attempt to modify the *type* of an | -| | | | | -| | | | Attribute shall result in a *BadRequest* error). | -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the natural language of data held in the request. | -| | | | | -| | | | When a merge operation applies to a pre-existing *LanguageProperty* and the value is supplied as a string or string array in the payload body, this query parameter shall be used to determine the key within the *languageMap* JSON Object to update. | -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| observedAt | String | 0..1 | It shall be a *DateTime* (see [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)). | -| | | | | -| | | | When a merge operation applies to a pre-existing Attribute which previously contained an *observedAt* sub-attribute, the value held in this query parameter shall be used if no specific *observedAt* sub-Attribute is found in the payload body. | -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| options | Comma separated list of strings | 0..1 | An alternative mechanism to include the *format* parameter. **Deprecated** | -| | | | | -| | | | When its value includes the keyword ["simplified"]{.HTML_Code} (or its synonym ["keyValues"]{.HTML_Code}), this indicates that a simplified representation of Entities has been provided as defined by [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation). | -| | | | | -| | | | If both *format* and *options* are present, the value of the *format* parameter shall take precedence. | -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+---------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.5.3.4-2 .TH} -Table 6.5.3.4-2: Merge Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity Fragment | 1 | Entity Fragment containing a complete representation of the Attributes to be merged. | -+===============+======================================================================+=============+============================================+==============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No content | All the Attributes were merged successfully. | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.6 Resource: entities/{entityId}/attrs/ {#tabresource-entitiesentityidattrs number="11.6"} - -### 6.6.1 Description {#tabdescription-64 number="11.6.1"} - -This resource represents all the Attributes (Properties or Relationships) of an NGSI-LD Entity. - -### 6.6.2 Resource definition {#tabresource-definition-2 number="11.6.2"} - -Resource URI: - -::: B1plus -- /entities/{entityId}/attrs -::: - -Resource URI variables for this resource are defined in [Table 6.6.2‑1](11-tabapi-http-binding.md#Table_6.6.2-1). - -::: {#Table_6.6.2-1 .TH} -Table 6.6.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-----------------------------------+ -| Name | Definition | -+===================================+===================================+ -| entityId | Id (URI) of the concerned entity | -+-----------------------------------+-----------------------------------+ -::: - -### 6.6.3 Resource methods {#tabresource-methods-2 number="11.6.3"} - -#### 6.6.3.1 POST {#tabpost-1 number="11.6.3.1"} - -This method is bound to the "Append Attributes" operation and shall exhibit the behaviour defined by [clause 5.6.3](10-tabapi-operation-definition.md#tabappend-attributes). The Entity identifier is the value of the resource URI variable "entityId". The data to be appended shall be contained in the HTTP request payload body. [Figure 6.6.3.1‑1](11-tabapi-http-binding.md#Figure_6.6.3.1-1) shows the Append Attributes interaction. - -::: FL -![](./media/image86.png){style="width:3.69444in;height:2.56944in"} -::: - -::: {#Figure_6.6.3.1-1 .TF} -Figure 6.6.3.1-1: Append Attributes interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.6.3.1‑1](11-tabapi-http-binding.md#Table_6.6.3.1-1) and [Table 6.6.3.1‑2](11-tabapi-http-binding.md#Table_6.6.3.1-2) describes the request body and possible responses. - -::: {#Table_6.6.3.1-1 .TH} -Table 6.6.3.1-1: Append Attributes URL parameters -::: - -::: TAL -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================================+=================+===============================================================================================================================================+ -| options | Comma separated list of strings | 0..1 | ["noOverwrite"]{.HTML_Code} indicates that no attribute overwrite shall be performed. | -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+---------------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.6.3.1-2 .TH} -Table 6.6.3.1-2: Append Attributes request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity Fragment | 1 | Entity Fragment containing a complete representation of the Attributes to be added. | -+===============+======================================================================+=============+============================================+====================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No content | All the Attributes were appended successfully. | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | Only the Attributes included in the response payload body were successfully appended. | -| | | | | | -| | | | | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.6.3.2 PATCH {#tabpatch-1 number="11.6.3.2"} - -This method is bound to the "Update Attributes" operation and shall exhibit the behaviour defined by [clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes). The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. [Figure 6.6.3.2‑1](11-tabapi-http-binding.md#Figure_6.6.3.2-1) shows the Update Attributes interaction. - -::: FL -![](./media/image87.png){style="width:3.69444in;height:2.56944in"} -::: - -::: {#Figure_6.6.3.2-1 .TF} -Figure 6.6.3.2-1: Update Attributes interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.6.3.2‑1](11-tabapi-http-binding.md#Table_6.6.3.2-1) and [Table 6.6.3.2‑2](11-tabapi-http-binding.md#Table_6.6.3.2-2) describes the request body and possible responses. - -::: {#Table_6.6.3.2-1 .TH} -Table 6.6.3.2-1: Update Attributes URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===============================================================================================================================================+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.6.3.2-2 .TH} -Table 6.6.3.2-2: Update Attributes request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity Fragment | 1 | Entity Fragment containing a complete representation of the Attributes to be updated. | -+===============+======================================================================+=============+=============================================+=================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No content | All the Attributes were updated successfully. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the *updated* array of *UpdateResult* (see [clause 5.2.18](10-tabapi-operation-definition.md#tabupdateresult)) will be empty. | -| | | | | | -| | | | | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.7 Resource: entities/{entityId}/attrs/{attrId} {#tabresource-entitiesentityidattrsattrid number="11.7"} - -### 6.7.1 Description {#tabdescription-65 number="11.7.1"} - -This resource represents an attribute (Property or Relationship) of an NGSI-LD Entity. - -### 6.7.2 Resource definition {#tabresource-definition-3 number="11.7.2"} - -Resource URI: - -::: B1plus -- /entities/{entityId}/attrs/{attrId} -::: - -Resource URI variables for this resource are defined in [Table 6.7.2‑1](11-tabapi-http-binding.md#Table_6.7.2-1). - -::: {#Table_6.7.2-1 .TH} -Table 6.7.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-------------------------------------------+ -| Name | Definition | -+===================================+===========================================+ -| entityId | Id (URI) of the concerned entity | -+-----------------------------------+-------------------------------------------+ -| attrId | Attribute name (Property or Relationship) | -+-----------------------------------+-------------------------------------------+ -::: - -### 6.7.3 Resource methods {#tabresource-methods-3 number="11.7.3"} - -#### 6.7.3.1 PATCH {#tabpatch-2 number="11.7.3.1"} - -This method is bound to the "Partial Attribute Update" operation and shall exhibit the behaviour defined by [clause 5.6.4](10-tabapi-operation-definition.md#tabpartial-attribute-update). The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". The Entity Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.1-1 shows the Partial Attribute Update interaction. - -::: FL -![](./media/image88.png){style="width:3.70833in;height:2.59722in"} -::: - -::: {#Figure_6.7.3.1-1 .TF} -Figure 6.7.3.1-1: Partial Attribute Update interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.7.3.1‑1](11-tabapi-http-binding.md#Table_6.7.3.1-1) and [Table 6.7.3.2‑2](11-tabapi-http-binding.md#Table_6.7.3.2-2) describes the request body and possible responses. - -::: {#Table_6.7.3.1-1 .TH} -Table 6.7.3.1-1: Partial Attribute Update URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===============================================================================================================================================+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.7.3.1-2 .TH} -Table 6.7.3.1-2: Partial Attribute Update request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAJ} | {TAJ} | {TAL} | -| | | | | -| | Entity Fragment | 1 | Entity Fragment containing the elements of the attribute to be updated. | -+===============+======================================================================+=============+======================================+======================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | The attribute was updated successfully. | -| +----------------------------------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *UpdateResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier or attribute name not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.7.3.2 DELETE {#tabdelete-2 number="11.7.3.2"} - -This method is associated to the operation "Delete Attribute" and shall exhibit the behaviour defined by [clause 5.6.5](10-tabapi-operation-definition.md#tabdelete-attribute). The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". [Figure 6.7.3.2‑1](11-tabapi-http-binding.md#Figure_6.7.3.2-1) shows the Delete Attribute interaction, [Table 6.7.3.2‑1](11-tabapi-http-binding.md#Table_6.7.3.2-1) shows the delete parameters to be supported and [Table 6.7.3.2‑2](11-tabapi-http-binding.md#Table_6.7.3.2-2) describes the request body and possible responses. - -::: FL -![](./media/image89.png){style="width:3.70833in;height:2.59722in"} -::: - -::: {#Figure_6.7.3.2-1 .TF} -Figure 6.7.3.2-1: Delete Attribute interaction -::: - -::: {#Table_6.7.3.2-1 .TH} -Table 6.7.3.2-1: Delete Attribute URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+======================================================================================================================================================================================================================================================+ -| datasetId | String | 0..1 | Shall be a valid URI. Specifies the *datasetId* of the dataset to be deleted. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deleteAll | Boolean | 0..1 | If *true*, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the *datasetId* is deleted. In case neither the deleteAll flag nor a *datasetId* is present, the default Attribute instance is deleted. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.7.3.2-2 .TH} -Table 6.7.3.2-2: Delete Attribute request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+==================+======================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *UpdateResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) or attribute name not known to the system. see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.7.3.3 PUT {#tabput-1 number="11.7.3.3"} - -This method is bound to the "Replace Attribute" operation and shall exhibit the behaviour defined by [clause 5.6.19](10-tabapi-operation-definition.md#tabreplace-attribute). The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". The Attribute Fragment shall be contained in the HTTP request payload body. [Figure 6.7.3.3‑1](11-tabapi-http-binding.md#Figure_6.7.3.3-1) shows the Replace Attribute interaction. - -::: FL -![](./media/image90.png){style="width:3.70833in;height:2.59722in"} -::: - -::: {#Figure_6.7.3.3-1 .TF} -Figure 6.7.3.3-1: Replace Attribute interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.7.3.3‑1](11-tabapi-http-binding.md#Table_6.7.3.3-1) and [Table 6.7.3.3‑2](11-tabapi-http-binding.md#Table_6.7.3.3-2) describes the request body and possible responses. - -::: {#Table_6.7.3.3-1 .TH} -Table 6.7.3.3-1: Replace Attribute URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===============================================================================================================================================+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.7.3.3-2 .TH} -Table 6.7.3.3-2: Replace Attribute request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAJ} | {TAJ} | {TAL} | -| | | | | -| | Attribute Fragment | 1 | Attribute Fragment replacing the previous data. | -+===============+======================================================================+=============+==========================+======================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | The attribute was replaced successfully. | -| +----------------------------------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *UpdateResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier or attribute name not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.8 Resource: csourceRegistrations/ {#tabresource-csourceregistrations number="11.8"} - -### 6.8.1 Description {#tabdescription-66 number="11.8.1"} - -This resource represents the context source registrations known to an NGSI-LD system. - -### 6.8.2 Resource definition {#tabresource-definition-4 number="11.8.2"} - -Resource URI: - -::: B1plus -- /csourceRegistrations/ -::: - -### 6.8.3 Resource methods {#tabresource-methods-4 number="11.8.3"} - -#### 6.8.3.1 POST {#tabpost-2 number="11.8.3.1"} - -This method is bound to the operation "Register Context Source" and shall exhibit the behaviour defined by [clause 5.9.2](10-tabapi-operation-definition.md#tabregister-context-source), taking the context source registration to be created from the HTTP request payload body. [Figure 6.8.3.1‑1](11-tabapi-http-binding.md#Figure_6.8.3.1-1) shows the Register Context Source interaction and [Table 6.8.3.1‑1](11-tabapi-http-binding.md#Table_6.8.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image91.png){style="width:3.36111in;height:1.84722in"} -::: - -::: {#Figure_6.8.3.1-1 .TF} -Figure 6.8.3.1-1: Register Context Source interaction -::: - -::: {#Table_6.8.3.1-1 .TH} -Table 6.8.3.1-1: Register Context Source request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | CSourceRegistration | 1 | Payload body in the request contains a JSON-LD object which represents the context source registration that is to be created. | -+===============+======================================================================+=============+=================================================================+======================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created context source registration. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that the context source registration already exists, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 422 Unprocessable | It is used to indicate that the operation is not available see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | [Context Source Registration]{.HTML_Keyboard} | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.8.3.2 GET {#tabget-2 number="11.8.3.2"} - -This method is associated to the operation "Query Context Source Registrations" and shall exhibit the behaviour defined by [clause 5.10.2](10-tabapi-operation-definition.md#tabquery-context-source-registrations), i.e. the parameters in the request describe entity related information, but instead of directly providing this entity information, the context source registration data, which describes context sources that can possibly provide the information, are returned as part of the HTTP response payload body. [Figure 6.8.3.2‑1](11-tabapi-http-binding.md#Figure_6.8.3.2-1) shows the Query Context Source Registrations interaction. - -::: FL -![](./media/image92.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.8.3.2-1 .TF} -Figure 6.8.3.2-1: Query Context Source Registrations interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.8.3.2‑1](11-tabapi-http-binding.md#Table_6.8.3.2-1) and Table 6.8.3.2-2 describes the request body and possible responses. - -::: {#Table_6.8.3.2-1 .TH} -Table 6.8.3.2-1: Query Context Source Registrations URL parameters -::: - -::: TAL -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+==================+====================================================================+=========================================================================+========================================================================================================================================================================================================================================================================================================+ -| attrs | Comma separated list strings | 0..1 | A synonym for a combination of the *pick* and*q* members. **Deprecated** | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present. | Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved. | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| coordinates | String | 0..1 | Coordinates serialized as a string as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be one if *geometry* or *georel* are present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | 0..1 | [Context Source]{.HTML_Keyboard} filter as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endTimeAt | String | 0..1 | It represents the *endTimeAt* parameter as defined by [clause 4.1](9-tabcontext-information-management-framework.md#tabintroduction). | -| | | | | -| | | | It shall be a *DateTime.* Cardinality shall be 1 if *timerel* is equal to ["between".]{.HTML_Code} | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | 0..1 | Geometry as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *georel* or *coordinates* are present. | | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometryProperty | String | 0..1 | It represents a Property name. | -| | | | | -| | | | In the case of GeoJSON Entity representation, this parameter indicates which *GeoProperty* to use for the top-level *geometry* field. | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoproperty | String | 0..1 | It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. | -| | | | | -| | | It shall be ignored if no geoquery is present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| georel | String | 0..1 | Geo relationship as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *geometry* or *coordinates* are present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id | Comma separated list of strings | 0..1 | Each String shall be a valid URI. List of entity ids to be retrieved. | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| idPattern | Regular expression as defined by [[11]](7-tabreferences.md#11) | 0..1 | Regular expression that shall be matched by entity ids satisfying the query | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the preferred natural language of the response. | -| | | | | -| | | | It is used to reduce *languageMaps* to a string or string array property in a single preferred language. | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or a projected Attribute name). | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | 0..1 | Query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | 0..1 | Scope query (see [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)). | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeAt | String | 0..1 | It represents the *timeAt* parameter as defined by [clause 4.1](9-tabcontext-information-management-framework.md#tabintroduction). | -| | | | | -| | | | It shall be a *DateTime*. Cardinality shall be 1 if *timerel* is present. | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeproperty | String | 0..1 | It represents a Temporal Property name. | -| | | | | -| | | It shall be ignored if no temporal query is present. | Allowed values: ["observedAt"]{.HTML_Code}, ["createdAt"]{.HTML_Code}, ["modifiedAt"]{.HTML_Code} and ["deletedAt"]{.HTML_Code}. If not specified, the default is ["observedAt"]{.HTML_Code}. (See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)). | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timerel | String | 0..1 | It represents the temporal relationship as defined by [clause 4.1](9-tabcontext-information-management-framework.md#tabintroduction). | -| | | | | -| | | | Allowed values: ["before"]{.HTML_Code}, ["after"]{.HTML_Code}, ["between".]{.HTML_Code} | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). | -| | | | | -| | | At least one among: *type*, *attrs*, *q*, or *georel* shall be present. | | -+------------------+--------------------------------------------------------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.8.3.2-2 .TH} -Table 6.8.3.2-2: Retrieve Context Source Registrations request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=======================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | CSourceRegistration[] | 1 | 200 OK | A response body containing the query result as an array of context source registrations. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.9 Resource: csourceRegistrations/{registrationId} {#tabresource-csourceregistrationsregistrationid number="11.9"} - -### 6.9.1 Description {#tabdescription-67 number="11.9.1"} - -This resource represents the context source registration, identified by *registrationId*, known to an NGSI-LD system. - -### 6.9.2 Resource definition {#tabresource-definition-5 number="11.9.2"} - -Resource URI: - -::: B1plus -- /csourceRegistrations/{registrationId} -::: - -Resource URI variables for this resource are defined in [Table 6.9.2‑1](11-tabapi-http-binding.md#Table_6.9.2-1). - -::: {#Table_6.9.2-1 .TH} -Table 6.9.2-1: URI variables -::: - -::: TAL -+-----------------------------------+---------------------------------------------+ -| Name | Definition | -+===================================+=============================================+ -| registrationId | Id (URI) of the context source registration | -+-----------------------------------+---------------------------------------------+ -::: - -### 6.9.3 Resource methods {#tabresource-methods-5 number="11.9.3"} - -#### 6.9.3.1 GET {#tabget-3 number="11.9.3.1"} - -This method is associated with the operation "Retrieve Context Source Registration" and shall exhibit the behaviour defined by [clause 5.10.1](10-tabapi-operation-definition.md#tabretrieve-context-source-registration). The registration identifier is the value of the resource URI variable "registrationId". Figure 6.9.3.1-1 shows the Retrieve Context Source Registration interaction and [Table 6.9.3.1‑1](11-tabapi-http-binding.md#Table_6.9.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image93.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.9.3.1-1 .TF} -Figure 6.9.3.1-1: Retrieve Context Source Registration interaction -::: - -::: {#Table_6.9.3.1-1 .TH} -Table 6.9.3.1-1: Retrieve Context Source Registration request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=============================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | CSourceRegistration | 1 | 200 OK | A response body containing the JSON-LD representation of the target context source registration. | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a context source registration identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.9.3.2 PATCH {#tabpatch-3 number="11.9.3.2"} - -This method is bound to the "Update Context Source Registration" operation and shall exhibit the behaviour defined by [clause 5.9.3](10-tabapi-operation-definition.md#tabupdate-context-source-registration). The context source registration identifier is the value of the resource URI variable "registrationId". The context source registration to be updated shall be contained in the HTTP request payload body. [Figure 6.9.3.2‑1](11-tabapi-http-binding.md#Figure_6.9.3.2-1) shows the Update Context Source Registration interaction and [Table 6.9.3.2‑1](11-tabapi-http-binding.md#Table_6.9.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image94.png){style="width:3.56944in;height:1.84722in"} -::: - -::: {#Figure_6.9.3.2-1 .TF} -Figure 6.9.3.2-1: Update Context Source Registration interaction -::: - -::: {#Table_6.9.3.2-1 .TH} -Table 6.9.3.2-1: Update Context Source Registration request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | CSourceRegistration Fragment | 1 | Payload body in the request contains a JSON-LD object which represents the context source registration that is to be updated. | -+===============+======================================================================+=============+=================================================================+=======================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | The context source registration was successfully updated. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a context source registration identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.9.3.3 DELETE {#tabdelete-3 number="11.9.3.3"} - -This method is associated to the operation "Delete Context Source Registration" and shall exhibit the behaviour defined by [clause 5.9.4](10-tabapi-operation-definition.md#tabdelete-context-source-registration). The context source registration identifier is the value of the resource URI variable "registrationId". [Figure 6.9.3.3‑1](11-tabapi-http-binding.md#Figure_6.9.3.3-1) shows the Delete Context Source Registration interaction and [Table 6.9.3.3‑1](11-tabapi-http-binding.md#Table_6.9.3.3-1) describes the request body and possible responses. - -::: FL -![](./media/image95.png){style="width:3.61111in;height:1.45833in"} -::: - -::: {#Figure_6.9.3.3-1 .TF} -Figure 6.9.3.3-1: Delete Context Source Registration interaction -::: - -::: {#Table_6.9.3.3-1 .TH} -Table 6.9.3.3-1: Delete Context Source Registration request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=============================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a context source registration identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.10 Resource: subscriptions/ {#tabresource-subscriptions number="11.10"} - -### 6.10.1 Description {#tabdescription-68 number="11.10.1"} - -This resource represents the subscriptions known to an NGSI-LD system. - -### 6.10.2 Resource definition {#tabresource-definition-6 number="11.10.2"} - -Resource URI: - -::: B1plus -- /subscriptions/ -::: - -### 6.10.3 Resource methods {#tabresource-methods-6 number="11.10.3"} - -#### 6.10.3.1 POST {#tabpost-3 number="11.10.3.1"} - -This method is bound to the operation "Create Subscription" and shall exhibit the behaviour defined by [clause 5.8.1](10-tabapi-operation-definition.md#tabcreate-subscription), taking the subscription to be created from the HTTP request payload body. [Figure 6.10.3.1‑1](11-tabapi-http-binding.md#Figure_6.10.3.1-1) shows the Create Subscription interaction and [Table 6.10.3.1‑1](11-tabapi-http-binding.md#Table_6.10.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image96.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.10.3.1-1 .TF} -Figure 6.10.3.1-1: Create Subscription interaction -::: - -::: {#Table_6.10.3.1-1 .TH} -Table 6.10.3.1-1: Create Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Subscription | 1 | Payload body in the request contains a JSON-LD object which represents the subscription that is to be created. | -+===============+======================================================================+=============+=========================================================+=======================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created subscription. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that the subscription already exists see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.10.3.2 GET {#tabget-4 number="11.10.3.2"} - -This method is associated to the operation "Query Subscriptions" and shall exhibit the behaviour defined by [clause 5.8.4](10-tabapi-operation-definition.md#tabquery-subscriptions), providing the subscription data as part of the HTTP response payload body. [Figure 6.10.3.2‑1](11-tabapi-http-binding.md#Figure_6.10.3.2-1) shows the Query Subscriptions interaction. - -::: FL -![](./media/image97.png){style="width:3.44444in;height:1.84722in"} -::: - -::: {#Figure_6.10.3.2-1 .TF} -Figure 6.10.3.2-1: Query Subscriptions interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.10.3.2‑1](11-tabapi-http-binding.md#Table_6.10.3.2-1) and Table 6.10.3.2-2 describes the request body and possible responses. - -::: {#Table_6.10.3.2-1 .TH} -Table 6.10.3.2-1: Query Subscriptions URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+=================================================+ -| limit | Number | 0..1 | Maximum number of subscriptions to be retrieved | -+-----------------+-----------------+-----------------+-------------------------------------------------+ -::: - -::: {#Table_6.10.3.2-2 .TH} -Table 6.10.3.2-2: Query Subscriptions request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=======================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | Subscription[] | 1 | 200 OK | A response body containing a list of subscriptions. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.11 Resource: subscriptions/{subscriptionId} {#tabresource-subscriptionssubscriptionid number="11.11"} - -### 6.11.1 Description {#tabdescription-69 number="11.11.1"} - -This resource represents a subscription known to an NGSI-LD system. - -### 6.11.2 Resource definition {#tabresource-definition-7 number="11.11.2"} - -Resource URI: - -::: B1plus -- /subscriptions/{subscriptionId} -::: - -Resource URI variables for this resource are defined in [Table 6.11.2‑1](11-tabapi-http-binding.md#Table_6.11.2-1). - -::: {#Table_6.11.2-1 .TH} -Table 6.11.2-1: URI variables -::: - -::: TAL -+-----------------------------------+----------------------------------------+ -| Name | Definition | -+===================================+========================================+ -| subscriptionId | Id (URI) of the concerned subscription | -+-----------------------------------+----------------------------------------+ -::: - -### 6.11.3 Resource methods {#tabresource-methods-7 number="11.11.3"} - -#### 6.11.3.1 GET {#tabget-5 number="11.11.3.1"} - -This method is associated to the operation "Retrieve Subscription" and shall exhibit the behaviour defined by [clause 5.8.3](10-tabapi-operation-definition.md#tabretrieve-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.11.3.1‑1](11-tabapi-http-binding.md#Figure_6.11.3.1-1) shows the Retrieve Subscription interaction and [Table 6.11.3.1‑1](11-tabapi-http-binding.md#Table_6.11.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image98.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.11.3.1-1 .TF} -Figure 6.11.3.1-1: Retrieve Subscription interaction -::: - -::: {#Table_6.11.3.1-1 .TH} -Table 6.11.3.1-1: Retrieve Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Subscription | 1 | 200 OK | A response body containing the JSON-LD representation of the target subscription. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.11.3.2 PATCH {#tabpatch-4 number="11.11.3.2"} - -This method is associated to the operation "Update Subscription" and shall exhibit the behaviour defined by [clause 5.8.2](10-tabapi-operation-definition.md#tabupdate-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.11.3.2‑1](11-tabapi-http-binding.md#Figure_6.11.3.2-1) shows the Update Subscription interaction and [Table 6.11.3.2‑1](11-tabapi-http-binding.md#Table_6.11.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image99.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.11.3.2-1 .TF} -Figure 6.11.3.2-1: Update Subscription interaction -::: - -::: {#Table_6.11.3.2-1 .TH} -Table 6.11.3.2-1: Update Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Subscription Fragment | 1 | Subscription Fragment including id, type and any other subscription field to be changed | -+===============+======================================================================+=============+==============================================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.11.3.3 DELETE {#tabdelete-4 number="11.11.3.3"} - -This method is associated to the operation "Delete Subscription" and shall exhibit the behaviour defined by [clause 5.8.5](10-tabapi-operation-definition.md#tabdelete-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.11.3.3‑1](11-tabapi-http-binding.md#Figure_6.11.3.3-1) shows the Delete Subscription interaction and [Table 6.11.3.3‑1](11-tabapi-http-binding.md#Table_6.11.3.3-1) describes the request body and possible responses. - -::: FL -![](./media/image100.png){style="width:3.45833in;height:1.45833in"} -::: - -::: {#Figure_6.11.3.3-1 .TF} -Figure 6.11.3.3-1: Delete Subscription interaction -::: - -::: {#Table_6.11.3.3-1 .TH} -Table 6.11.3.3-1: Delete Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.12 Resource: csourceSubscriptions/ {#tabresource-csourcesubscriptions number="11.12"} - -### 6.12.1 Description {#tabdescription-70 number="11.12.1"} - -This resource represents the context source registration subscriptions known to an NGSI-LD system. - -### 6.12.2 Resource definition {#tabresource-definition-8 number="11.12.2"} - -Resource URI: - -::: B1plus -- /csourceSubscriptions/ -::: - -### 6.12.3 Resource methods {#tabresource-methods-8 number="11.12.3"} - -#### 6.12.3.1 POST {#tabpost-4 number="11.12.3.1"} - -This method is bound to the operation "Create Context Source Registration Subscription" and shall exhibit the behaviour defined by [clause 5.11.2](10-tabapi-operation-definition.md#tabcreate-context-source-registration-subscription), taking the context source registration subscription to be created from the HTTP request payload body. [Figure 6.12.3.1‑1](11-tabapi-http-binding.md#Figure_6.12.3.1-1) shows the Create Context Source Registration Subscription interaction and [Table 6.12.3.1‑1](11-tabapi-http-binding.md#Table_6.12.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image101.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.12.3.1-1 .TF} -Figure 6.12.3.1-1: Create Context Source Registration Subscription interaction -::: - -::: {#Table_6.12.3.1-1 .TH} -Table 6.12.3.1-1: Create Context Source Registration Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Subscription | 1 | Payload body in the request contains a JSON-LD object which represents the context source registration subscription that is to be created. | -+===============+======================================================================+=============+=======================================================================+===================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created context source registration subscription. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that the context source registration subscription already exists, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.12.3.2 GET {#tabget-6 number="11.12.3.2"} - -This method is associated to the operation "Query Context Source Registration Subscriptions" and shall exhibit the behaviour defined by [clause 5.11.5](10-tabapi-operation-definition.md#tabquery-context-source-registration-subscriptions), providing the context source registration subscription data as part of the HTTP response payload body. [Figure 6.12.3.2‑1](11-tabapi-http-binding.md#Figure_6.12.3.2-1) shows the Query Context Source Registration Subscriptions interaction. - -::: FL -![](./media/image102.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.12.3.2-1 .TF} -Figure 6.12.3.2-1: Query Context Source Registration Subscriptions interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.12.3.2‑1](11-tabapi-http-binding.md#Table_6.12.3.2-1) and Table 6.12.3.2-2 describes the request body and possible responses. - -::: {#Table_6.12.3.2-1 .TH} -Table 6.12.3.2-1: Query Context Source Registration Subscriptions URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+=================================================+ -| limit | Number | 0..1 | Maximum number of subscriptions to be retrieved | -+-----------------+-----------------+-----------------+-------------------------------------------------+ -::: - -::: {#Table_6.12.3.2-2 .TH} -Table 6.12.3.2-2: Query Context Source Registration Subscriptions request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=======================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | Subscription[] | 1 | 200 OK | A response body containing a list of context source registration subscriptions. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.13 Resource: csourceSubscriptions/{subscriptionId} {#tabresource-csourcesubscriptionssubscriptionid number="11.13"} - -### 6.13.1 Description {#tabdescription-71 number="11.13.1"} - -This resource represents the context source registration subscription, identified by *subscriptionId*, known to an NGSI-LD system. - -### 6.13.2 Resource definition {#tabresource-definition-9 number="11.13.2"} - -Resource URI: - -::: B1plus -- /csourceSubscriptions/{subscriptionId} -::: - -Resource URI variables for this resource are defined in [Table 6.13.2‑1](11-tabapi-http-binding.md#Table_6.13.2-1). - -::: {#Table_6.13.2-1 .TH} -Table 6.13.2-1: URI variables -::: - -::: TAL -+-----------------------------------+---------------------------------------------------------------------+ -| Name | Definition | -+===================================+=====================================================================+ -| subscriptionId | Id (URI) of the concerned context source registration subscription. | -+-----------------------------------+---------------------------------------------------------------------+ -::: - -### 6.13.3 Resource methods {#tabresource-methods-9 number="11.13.3"} - -#### 6.13.3.1 GET {#tabget-7 number="11.13.3.1"} - -This method is associated to the operation "Retrieve Context Source Registration Subscription" and shall exhibit the behaviour defined by [clause 5.11.4](10-tabapi-operation-definition.md#tabretrieve-context-source-registration-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.13.3.1‑1](11-tabapi-http-binding.md#Figure_6.13.3.1-1) shows the Retrieve Context Source Registration interaction and [Table 6.13.3.1‑1](11-tabapi-http-binding.md#Table_6.13.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image103.png){style="width:3.54167in;height:1.83333in"} -::: - -::: {#Figure_6.13.3.1-1 .TF} -Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription interaction -::: - -::: {#Table_6.13.3.1-1 .TH} -Table 6.13.3.1-1: Retrieve Context Source Registration Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Subscription | 1 | 200 OK | A response body containing the JSON-LD representation of the target context source registration subscription. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.13.3.2 PATCH {#tabpatch-5 number="11.13.3.2"} - -This method is associated to the operation "Update Context Source Registration Subscription" and shall exhibit the behaviour defined by [clause 5.11.3](10-tabapi-operation-definition.md#tabupdate-context-source-registration-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.13.3.2‑1](11-tabapi-http-binding.md#Figure_6.13.3.2-1) shows the Update Context Source Registration Subscription interaction and Table 6.13.3.2-1 describes the request body and possible responses. - -::: FL -![](./media/image104.png){style="width:3.56944in;height:1.84722in"} -::: - -::: {#Figure_6.13.3.2-1 .TF} -Figure 6.13.3.2-1: Update Context Source Registration Subscription interaction -::: - -::: {#Table_6.13.3.2-1 .TH} -Table 6.13.3.2-1: Update Context Source Registration Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Subscription Fragment | 1 | Subscription Fragment including id, type and any other context source registration subscription field to be changed. | -+===============+======================================================================+=============+============================================================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.13.3.3 DELETE {#tabdelete-5 number="11.13.3.3"} - -This method is associated to the operation "Delete Context Source Registration Subscription" and shall exhibit the behaviour defined by [clause 5.11.6](10-tabapi-operation-definition.md#tabdelete-context-source-registration-subscription). The subscription identifier is the value of the resource URI variable "subscriptionId". [Figure 6.13.3.3‑1](11-tabapi-http-binding.md#Figure_6.13.3.3-1) shows the Delete Context Source Registration Subscription interaction and Table 6.13.3.3-1 describes the request body and possible responses. - -::: FL -![](./media/image105.png){style="width:3.75in;height:1.45833in"} -::: - -::: {#Figure_6.13.3.3-1 .TF} -Figure 6.13.3.3-1: Delete Context Source Registration Subscription interaction -::: - -::: {#Table_6.13.3.3-1 .TH} -Table 6.13.3.3-1: Delete Context Source Registration Subscription request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+==============================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a subscription identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.14 Resource: entityOperations/create {#tabresource-entityoperationscreate number="11.14"} - -### 6.14.1 Description {#tabdescription-72 number="11.14.1"} - -A sub-resource, pertaining to the *entityOperations/* resource, intended to enable batch entity creation for the NGSI-LD API. - -### 6.14.2 Resource definition {#tabresource-definition-10 number="11.14.2"} - -Resource URI: - -::: B1plus -- /entityOperations/create -::: - -### 6.14.3 Resource methods {#tabresource-methods-10 number="11.14.3"} - -#### 6.14.3.1 POST {#tabpost-5 number="11.14.3.1"} - -This method is associated to the operation "Batch Entity Creation" and shall exhibit the behaviour defined by [clause 5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation). [Figure 6.14.3.1‑1](11-tabapi-http-binding.md#Figure_6.14.3.1-1) shows the operation interaction and [Table 6.14.3.1‑1](11-tabapi-http-binding.md#Table_6.14.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image106.png){style="width:3.97222in;height:2.94444in"} -::: - -::: {#Figure_6.14.3.1-1 .TF} -Figure 6.14.3.1-1: Batch Entity Creation interaction -::: - -::: {#Table_6.14.3.1-1 .TH} -Table 6.14.3.1-1: Batch Entity Creation request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity[] | 1 | Array of entities to be created. | -+===============+======================================================================+=============+==================+========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Code | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | String[] | 1 | 201 Created | If all entities have been successfully created, an array of Strings containing URIs is returned in the response. Each URI represents the Entity ID of a created entity. There is no restriction as to the order of the Entity IDs. | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully created entities, while the second array (*errors*) contains information about the error for each of the entities that could not be created. There is no restriction as to the order of the Entity IDs in the arrays. | -| | | | | | -| | | | | If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.15 Resource: entityOperations/upsert {#tabresource-entityoperationsupsert number="11.15"} - -### 6.15.1 Description {#tabdescription-73 number="11.15.1"} - -A sub-resource, pertaining to the *entityOperations*/ resource, intended to enable batch entity creation or update for the NGSI-LD API. - -### 6.15.2 Resource definition {#tabresource-definition-11 number="11.15.2"} - -Resource URI: - -::: B1plus -- /entityOperations/upsert -::: - -### 6.15.3 Resource methods {#tabresource-methods-11 number="11.15.3"} - -#### 6.15.3.1 POST {#tabpost-6 number="11.15.3.1"} - -This method is associated to the operation "Batch Entity Creation or Update (Upsert)" and shall exhibit the behaviour defined by [clause 5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert). [Figure 6.15.3.1‑1](11-tabapi-http-binding.md#Figure_6.15.3.1-1) shows the operation interaction and [Table 6.15.3.1‑1](11-tabapi-http-binding.md#Table_6.15.3.1-1) describes the request body and possible responses. - -The *options* query parameter for this request can take the following values: - -::: B1plus -- ["replace"]{.HTML_Code}. Indicates that all the existing Entity content shall be replaced (default mode); -- ["update"]{.HTML_Code}. Indicates that existing Entity content shall be updated. -::: - -::: FL -![](./media/image107.png){style="width:3.91667in;height:3.26389in"} -::: - -::: {#Figure_6.15.3.1-1 .TF} -Figure 6.15.3.1-1: Batch Entity Creation or Update interaction -::: - -::: {#Table_6.15.3.1-1 .TH} -Table 6.15.3.1-1: Batch Entity Creation or Update request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity[] | 1 | Array of entities to be created/updated. | -+===============+======================================================================+=============+======================+=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Code | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | String[] | 1 | 201 Created | If all entities not existing prior to this request have been successfully created and the others have been successfully updated, an array of String (with the URIs representing the Entity IDs of the created entities only) is returned in the response. There is no restriction as to the order of the Entity IDs. The merely updated entities do not take part in the response (corresponding to 204 No Content returned in the case of updates). | -| +----------------------------------------------------------------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | If all entities already existed and are successfully updated, there is no payload body in the response. | -| +----------------------------------------------------------------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully created or updated entities, while the second array (*errors*) contains information about the error for each of the entities that could not be created or updated. There is no restriction as to the order of the Entity IDs in the arrays. | -| | | | | | -| | | | | If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.16 Resource: entityOperations/update {#tabresource-entityoperationsupdate number="11.16"} - -### 6.16.1 Description {#tabdescription-74 number="11.16.1"} - -A sub-resource, pertaining to the *entityOperations*/ resource, intended to enable batch entity update for the NGSI-LD API. - -### 6.16.2 Resource definition {#tabresource-definition-12 number="11.16.2"} - -Resource URI: - -::: B1plus -- /entityOperations/update -::: - -### 6.16.3 Resource methods {#tabresource-methods-12 number="11.16.3"} - -#### 6.16.3.1 POST {#tabpost-7 number="11.16.3.1"} - -This method is associated to the operation "Batch Entity Update" and shall exhibit the behaviour defined by [clause 5.6.9](10-tabapi-operation-definition.md#tabbatch-entity-update). [Figure 6.16.3.1‑1](11-tabapi-http-binding.md#Figure_6.16.3.1-1) shows the operation interaction and [Table 6.16.3.1‑1](11-tabapi-http-binding.md#Table_6.16.3.1-1) describes the request body and possible responses. - -The *options* query parameter for this request can take the following values: - -::: B1plus -- ["noOverwrite".]{.HTML_Code} Indicates that no attribute overwrite shall be performed. -::: - -::: FL -![](./media/image108.png){style="width:3.91667in;height:2.52778in"} -::: - -::: {#Figure_6.16.3.1-1 .TF} -Figure 6.16.3.1-1: Batch Entity Update interaction -::: - -::: {#Table_6.16.3.1-1 .TH} -Table 6.16.3.1-1: Batch Entity Update request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity[] | 1 | Array of Entities to be updated | -+===============+======================================================================+=============+==================+========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Code | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | If all entities have been successfully updated, there is no payload body in the response. | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If only some or none of the entities have been successfully updated, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully updated entities, while the second array (*errors*) contains information about the error for each of the entities that could not be updated. There is no restriction as to the order of the Entity IDs in the arrays. | -| | | | | | -| | | | | If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.17 Resource: entityOperations/delete {#tabresource-entityoperationsdelete number="11.17"} - -### 6.17.1 Description {#tabdescription-75 number="11.17.1"} - -A sub-resource, pertaining to the *entityOperations*/ resource, intended to enable batch entity deletion for the NGSI-LD API. - -### 6.17.2 Resource definition {#tabresource-definition-13 number="11.17.2"} - -Resource URI: - -::: B1plus -- /entityOperations/delete -::: - -### 6.17.3 Resource methods {#tabresource-methods-13 number="11.17.3"} - -#### 6.17.3.1 POST {#tabpost-8 number="11.17.3.1"} - -This method is associated to the operation "Batch Entity Delete" and shall exhibit the behaviour defined by [clause 5.6.10](10-tabapi-operation-definition.md#tabbatch-entity-delete). [Figure 6.17.3.1‑1](11-tabapi-http-binding.md#Figure_6.17.3.1-1) shows the operation interaction and [Table 6.17.3.1‑1](11-tabapi-http-binding.md#Table_6.17.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image109.png){style="width:3.6573in;height:2.35577in"} -::: - -::: {#Figure_6.17.3.1-1 .TF} -Figure 6.17.3.1-1: Batch Entity Delete interaction -::: - -::: {#Table_6.17.3.1-1 .TH} -Table 6.17.3.1-1: Batch Entity Delete request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | String[] | 1 | Array of String (URIs representing Entity IDs) to be deleted | -+===============+======================================================================+=============+================================+========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Code | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | If all entities existed and have been successfully deleted, there is no payload body in the response. | -| +----------------------------------------------------------------------+-------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully deleted entities, while the second array (*errors*) contains information about the error for each of the entities that could not be deleted. There is no restriction as to the order of the Entity IDs in the arrays. | -| | | | | | -| | | | | If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.18 Resource: temporal/entities/ {#tabresource-temporalentities number="11.18"} - -### 6.18.1 Description {#tabdescription-76 number="11.18.1"} - -This resource represents the [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[E]{.HTML_Keyboard}[volution of Entities]{.HTML_Keyboard} known to an NGSI-LD system. - -### 6.18.2 Resource definition {#tabresource-definition-14 number="11.18.2"} - -Resource URI: - -::: B1plus -- /temporal/entities/ -::: - -### 6.18.3 Resource methods {#tabresource-methods-14 number="11.18.3"} - -#### 6.18.3.1 POST {#tabpost-9 number="11.18.3.1"} - -This method is associated to the operation "Create or Update Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.6.11](10-tabapi-operation-definition.md#tabcreate-or-update-upsert-temporal-evolution-of-an-entity), taking the temporal representation of Entity to be created from the HTTP request payload body. [Figure 6.18.3.1‑1](11-tabapi-http-binding.md#Figure_6.18.3.1-1) shows this interaction and [Table 6.18.3.1‑1](11-tabapi-http-binding.md#Table_6.18.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image110.png){style="width:3.70833in;height:2.45833in"} -::: - -::: {#Figure_6.18.3.1-1 .TF} -Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity interaction -::: - -::: {#Table_6.18.3.1-1 .TH} -Table 6.18.3.1-1: Create or Update Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | EntityTemporal | 1 | Payload body in the request contains a JSON-LD object which represents the temporal representation of the Entity that is to be created (or updated). | -+===============+======================================================================+=============+============================================================================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | Upon creation success, the HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created entity. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | Upon update success. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* member should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 422 Unprocessable Entity | It is used to indicate that the operation is not available, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.18.3.2 GET {#tabget-8 number="11.18.3.2"} - -This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities), providing the Temporal Evolution of the matching Entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Query Temporal Evolution of Entities" operations via POST is defined in [clause 6.24](11-tabapi-http-binding.md#tabresource-temporalentityoperationsquery). [Figure 6.18.3.2‑1](11-tabapi-http-binding.md#Figure_6.18.3.2-1) shows this interaction. - -::: FL -![](./media/image111.png){style="width:5.27778in;height:3.72222in"} -::: - -::: {#Figure_6.18.3.2-1 .TF} -Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.18.3.2‑1](11-tabapi-http-binding.md#Table_6.18.3.2-1) and Table 6.18.3.2-2 describes the request body and possible responses. - -::: {#Table_6.18.3.2-1 .TH} -Table 6.18.3.2-1: Query Temporal Evolution of Entities URL parameters -::: - -::: TAL -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+====================+====================================================================+==========================================================================================================================================================================================================+=============================================================================================================================================================================================================================================================================================================================================================================+ -| aggrMethods | Comma separated list of strings | 0..1 | Each String represents an aggregation method, as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). Only applicable if ["aggregatedValues"]{.HTML_Code} is present in the *format* *or* *options* parameter. | -| | | | | -| | | It shall be 1 if *aggregatedValues* is present in the *options* parameter | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| aggrPeriodDuration | String | 0..1 | It represents the duration of each period used for the aggregation as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. | -| | | | | -| | | | Only applicable if ["aggregatedValues"]{.HTML_Code}is present in the *format* *or* *options* parameter. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| attrs | Comma separated list of strings | 0..1 | A synonym for a combination of the *pick* and*q* parameters. **Deprecated** | -| | | | | -| | | It shall be 1 if *type* is not present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| collation | String | 0..1 | An ICU collation (see IETF RFC 6067 [[36]](7-tabreferences.md#36)), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| coordinates | String | 0..1 | Coordinates serialized as a string as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be one if *georel* or *geometry* are present | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| csf | String | 0..1 | [Context Source]{.HTML_Keyboard} filter as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | Comma separated list of strings | 0..1 | Shall be valid URIs, ["@none"]{.HTML_Code} for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endTimeAt | String | 0..1 | It is representing the *endTimeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). It shall be a *DateTime.* Cardinality shall be 1 if *timerel* is equal to "between". | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMap | Boolean | 0..1 | If *true*, the location of the EntityMap used in the operation is returned in the response. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| entityMapLifetime | String | 0..1 | Suggested duration, represented in ISO 8601 [[17]](7-tabreferences.md#17) format, for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if *entityMap* is set to *true*. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| expandValues | Comma separated list of strings | 0..1 | Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied *\@context* prior to executing a query. It is part of query. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geometry | String | 0..1 | Geometry as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *georel* or *coordinates* are present | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| geoproperty | String | 0..1 | The name of the *GeoProperty* that contains the geospatial data that will be used to resolve the geoquery. By default, will be *location*. (See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties)). | -| | | | | -| | | It shall be ignored if no geoquery is present | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| georel | String | 0..1 | Geo relationship as per [clause 4.10](9-tabcontext-information-management-framework.md#tabngsi-ld-geoquery-language). It is part of geoquery. | -| | | | | -| | | It shall be 1 if *geometry* or *coordinates* are present | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id | Comma separated list of strings | 0..1 | Each String shall be a valid URI. List of entity ids to be retrieved. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| idPattern | Regular expression as defined by [[11]](7-tabreferences.md#11) | 0..1 | Regular expression that shall be matched by entity ids. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| jsonKeys | Comma separated list of strings | 0..1 | Each String is an Attribute (Property or Relationship) name. | -| | | | | -| | | | Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied *\@context* using JSON-LD type coercion prior to executing the query. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the preferred natural language of the response. It is used to reduce *languageMaps* to a string or string array property in a single preferred language. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastN | Positive integer | 0..1 | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name). | -| | | | | -| | | | When defined, the listed Entity members are removed from each Entity within the payload. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| orderBy | String | 0..1 | The Entity member (["id"]{.HTML_Code}) appended with an optional sorting style (["asc"]{.HTML_Code}, ["desc") ]{.HTML_Code}as per [clause 4.23](9-tabcontext-information-management-framework.md#tabentity-ordering). When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name). | -| | | | | -| | | | When defined, every Entity within the payload body is reduced down to only contain the listed Entity members. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| q | String | 0..1 | Query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| scopeQ | String | 0..1 | Scope query (see [clause 4.19](9-tabcontext-information-management-framework.md#tabngsi-ld-scope-query-language)). | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| splitEntities | Boolean | 0..1 | If *true* it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If *false* it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. | -| | | | | -| | | | The parameter does not apply in case *local*is *true*. | -| | | | | -| | | | The default value should be decided by implementation; it should be configurable. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeAt | String | 1 | representing the *timeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). It shall be a *DateTime.* | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeproperty | String | 0..1 | It represents a Temporal Property name. Allowed values: ["observedAt"]{.HTML_Code}, ["createdAt"]{.HTML_Code}, ["modifiedAt"]{.HTML_Code} and ["deletedAt"]{.HTML_Code}. If not specified, the default is ["observedAt"]{.HTML_Code}. (See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)). | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timerel | String | 1 | It represents the temporal relationship as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). Allowed values: ["before"]{.HTML_Code}, ["after"]{.HTML_Code}, ["between"]{.HTML_Code}. | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| type | String | 0..1 | Selection of Entity Types as per [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language). ["\*"]{.HTML_Code} is also allowed as a value and *local* is implicitly set to *true* and shall not be explicitly set to*false*. | -| | | | | -| | | It shall be 1 if *attrs* is not present, unless the execution of the request is limited to local scope (see [clause 5.5.13](10-tabapi-operation-definition.md#tablimiting-operations-to-local-scope)). | | -+--------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.18.3.2-2 .TH} -Table 6.18.3.2-2: Query Temporal Evolution of Entities request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=========================================================+============================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTemporal[] | 1 | 200 OK | A response body containing the query result as a list of temporal representation of Entities. | -| | | | | | -| | | | 201 Created (in case an EntityMap has been (re)created) | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTemporal[] | 1 | 203 Non-Authoritative Information | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | -| | | | | | -| | | | | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.19 Resource: temporal/entities/{entityId} {#tabresource-temporalentitiesentityid number="11.19"} - -### 6.19.1 Description {#tabdescription-77 number="11.19.1"} - -This resource is associated to the [T]{.HTML_Keyboard}[emporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard} known to an NGSI-LD system. - -### 6.19.2 Resource definition {#tabresource-definition-15 number="11.19.2"} - -Resource URI: - -::: B1plus -- /temporal/entities/{entityId} -::: - -Resource URI variables for this resource are defined in [Table 6.19.2‑1](11-tabapi-http-binding.md#Table_6.19.2-1). - -::: {#Table_6.19.2-1 .TH} -Table 6.19.2-1: URI variables -::: - -::: TAL -+-----------------------------------+----------------------------------------+ -| Name | Definition | -+===================================+========================================+ -| entityId | Id (URI) of the entity to be retrieved | -+-----------------------------------+----------------------------------------+ -::: - -### 6.19.3 Resource methods {#tabresource-methods-15 number="11.19.3"} - -#### 6.19.3.1 GET {#tabget-9 number="11.19.3.1"} - -This method is associated to the operation "Retrieve Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.7.3](10-tabapi-operation-definition.md#tabretrieve-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. [Figure 6.19.3.1‑1](11-tabapi-http-binding.md#Figure_6.19.3.1-1) shows the retrieve temporal representation of an entity interaction. - -::: FL -![](./media/image112.png){style="width:3.41667in;height:2.58333in"} -::: - -::: {#Figure_6.19.3.1-1 .TF} -Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction -::: - -The URL parameters that shall be supported are those defined in [Table 6.19.3.1‑1](11-tabapi-http-binding.md#Table_6.19.3.1-1) and [Table 6.19.3.1‑2](11-tabapi-http-binding.md#Table_6.19.3.1-2) describes the request body and possible responses. - -::: {#Table_6.19.3.1-1 .TH} -Table 6.19.3.1-1: Retrieve Temporal Evolution of an Entity URL parameters -::: - -::: TAL -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+====================+=================================+===========================================================================+===================================================================================================================================================================================================================================================================================================================================================================+ -| aggrMethods | Comma separated list of strings | 0..1 | Each String represents the aggregation methods as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). Only applicable if ["aggregatedValues"]{.HTML_Code} is present in the *format* *or* *options* parameter. | -| | | | | -| | | It shall be 1 if *aggregatedValues* is present in the *options* parameter | | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| aggrPeriodDuration | String | 0..1 | It represents the duration of each period used for the aggregation as defined by [clause 4.5.19](9-tabcontext-information-management-framework.md#tabaggregated-temporal-representation-of-an-entity). If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. | -| | | | | -| | | | Only applicable if "[aggregatedValues"]{.HTML_Code}is present in the *format* *or* *options* parameter. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| attrs | Comma separated list of strings | 0..1 | A synonym for the *pick* parameter, except that *id, type, scope* are not allowed. **Deprecated** | -| | | | | -| | | | Each String is an Attribute (Property or Relationship) name. List of Attributes to be retrieved. If not specified, all Attributes related to the temporal representation of an Entity shall be retrieved. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| datasetId | Comma separated list of strings | 0..1 | Shall be valid URIs, ["@none"]{.HTML_Code} for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| endTimeAt | String | 0..1 | It represents the *endTimeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). It shall be a *DateTime.* | -| | | | | -| | | It shall be 1 if *timerel* is equal to "between" | | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lang | String | 0..1 | It represents the preferred natural language of the response. It is used to reduce *languageMaps* to a string or string array property in a single preferred language. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastN | Positive integer | 0..1 | Only the last n Attribute instances (under the concerned time interval) shall be retrieved. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| omit | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name). | -| | | | | -| | | | When defined, the listed Entity members are removed from each Entity within the payload. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| pick | Comma separated list of strings | 0..1 | Each String is an Entity member (["id"]{.HTML_Code}, ["type"]{.HTML_Code}, ["scope"]{.HTML_Code} or an Attribute name). | -| | | | | -| | | | When defined, every Entity within the payload body is reduced down to only contain the listed Entity members. | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeAt | String | 0..1 | It represents the *timeAt* parameter as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). It shall be a *DateTime*. | -| | | | | -| | | It shall be 1 if *timerel* is present | | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timeproperty | String | 0..1 | It represents a Temporal Property name. Allowed values: ["observedAt"]{.HTML_Code}, ["createdAt"]{.HTML_Code}, ["modifiedAt"]{.HTML_Code} and ["deletedAt"]{.HTML_Code}. If not specified, the default is ["observedAt"]{.HTML_Code}. (See [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)). | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| timerel | String | 0..1 | It represents the Temporal Relationship as defined by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). Allowed values: ["before"]{.HTML_Code}, ["after"]{.HTML_Code}, ["between"]{.HTML_Code}. | -| | | | | -| | | It shall be 1 if *timeAt* is present | | -+--------------------+---------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.19.3.1-2 .TH} -Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+===================================+============================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTemporal | 1 | 200 OK | A response body containing the JSON-LD temporal representation of the target Entity containing the selected Attributes. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTemporal | 1 | 203 Non-Authoritative Information | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | -| | | | | | -| | | | | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.19.3.2 DELETE {#tabdelete-6 number="11.19.3.2"} - -This method is associated to the operation "Delete Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.6.16](10-tabapi-operation-definition.md#tabdelete-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. [Figure 6.19.3.2‑1](11-tabapi-http-binding.md#Figure_6.19.3.2-1) shows the delete entity interaction and [Table 6.19.3.2‑1](11-tabapi-http-binding.md#Table_6.19.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image113.png){style="width:3.41667in;height:1.45833in"} -::: - -::: {#Figure_6.19.3.2-1 .TF} -Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction -::: - -::: {#Table_6.19.3.2-1 .TH} -Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.20 Resource: temporal/entities/{entityId}/attrs/ {#tabresource-temporalentitiesentityidattrs number="11.20"} - -### 6.20.1 Description {#tabdescription-78 number="11.20.1"} - -This resource represents all the Attributes (Properties or Relationships) of a [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -### 6.20.2 Resource definition {#tabresource-definition-16 number="11.20.2"} - -Resource URI: - -::: B1plus -- /temporal/entities/{entityId}/attrs/ -::: - -Resource URI variables for this resource are defined in [Table 6.20.2‑1](11-tabapi-http-binding.md#Table_6.20.2-1). - -::: {#Table_6.20.2-1 .TH} -Table 6.20.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-----------------------------------+ -| Name | Definition | -+===================================+===================================+ -| entityId | Id (URI) of the concerned entity | -+-----------------------------------+-----------------------------------+ -::: - -### 6.20.3 Resource methods {#tabresource-methods-16 number="11.20.3"} - -#### 6.20.3.1 POST {#tabpost-10 number="11.20.3.1"} - -This method is bound to the "Add Attributes to Temporal Evolution of an Entity" operation and shall exhibit the behaviour defined by [clause 5.6.12](10-tabapi-operation-definition.md#tabadd-attributes-to-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. The data to be added shall be contained in the HTTP request payload body. [Figure 6.20.3.1‑1](11-tabapi-http-binding.md#Figure_6.20.3.1-1) shows the Add Attributes interaction and [Table 6.20.3.1‑1](11-tabapi-http-binding.md#Table_6.20.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image114.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.20.3.1-1 .TF} -Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity interaction -::: - -::: {#Table_6.20.3.1-1 .TH} -Table 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | EntityTemporal Fragment | 1 | EntityTemporal Fragment containing a complete representation of the Attribute instances to be added. | -+===============+======================================================================+=============+====================================================+=========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No content | All the Attributes were added successfully. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.21 Resource: temporal/entities/{entityId}/attrs/{attrId} {#tabresource-temporalentitiesentityidattrsattrid number="11.21"} - -### 6.21.1 Description {#tabdescription-79 number="11.21.1"} - -This resource represents an Attribute (Property or Relationship) of a [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -### 6.21.2 Resource definition {#tabresource-definition-17 number="11.21.2"} - -Resource URI: - -::: B1plus -- /temporal/entities/{entityId}/attrs/{attrId} -::: - -Resource URI variables for this resource are defined in [Table 6.21.2‑1](11-tabapi-http-binding.md#Table_6.21.2-1). - -::: {#Table_6.21.2-1 .TH} -Table 6.21.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-------------------------------------------+ -| Name | Definition | -+===================================+===========================================+ -| entityId | Id (URI) of the concerned entity | -+-----------------------------------+-------------------------------------------+ -| attrId | Attribute name (Property or Relationship) | -+-----------------------------------+-------------------------------------------+ -::: - -### 6.21.3 Resource methods {#tabresource-methods-17 number="11.21.3"} - -#### 6.21.3.1 DELETE {#tabdelete-7 number="11.21.3.1"} - -This method is associated to the operation "Delete Attribute from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.6.13](10-tabapi-operation-definition.md#tabdelete-attribute-from-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. The Attribute name is the value of the resource URI variable *attrId*. [Figure 6.21.3.1‑1](11-tabapi-http-binding.md#Figure_6.21.3.1-1) shows the "Delete Attribute from Temporal Evolution of an Entity" interaction, [Table 6.21.3.1‑1](11-tabapi-http-binding.md#Table_6.21.3.1-1) shows the delete parameters to be supported and Table 6.21.3.1-2 describes the request body and possible responses. - -::: FL -![](./media/image115.png){style="width:3.86111in;height:1.45833in"} -::: - -::: {#Figure_6.21.3.1-1 .TF} -Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity interaction -::: - -::: {#Table_6.21.3.1-1 .TH} -Table 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | Data Type | Cardinality | Remarks | -+=================+=================+=================+======================================================================================================================================================================================================================================================+ -| datasetId | String | 0..1 | Shall be a valid URI. Specifies the *datasetId* of the dataset to be deleted. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| deleteAll | Boolean | 0..1 | If *true,* all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the *datasetId* is deleted. In case neither the deleteAll flag nor a *datasetId* is present, the default Attribute instance is deleted. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.21.3.1-2 .TH} -Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+===========================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) or Attribute name not known to the system. See [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId} {#tabresource-temporalentitiesentityidattrsattrid-instanceid number="11.22"} - -### 6.22.1 Description {#tabdescription-80 number="11.22.1"} - -This resource represents an Attribute (Property or Relationship) instance of a [Temporal ]{.HTML_Keyboard}[Evolution ]{.HTML_Keyboard}[of an Entity]{.HTML_Keyboard}. - -### 6.22.2 Resource definition {#tabresource-definition-18 number="11.22.2"} - -Resource URI: - -::: B1plus -- /temporal/entities/{entityId}/attrs/{attrId}/{instanceId} -::: - -Resource URI variables for this resource are defined in [Table 6.22.2‑1](11-tabapi-http-binding.md#Table_6.22.2-1). - -::: {#Table_6.22.2-1 .TH} -Table 6.22.2-1: URI variables -::: - -::: TAL -+-----------------------------------+------------------------------------------------------+ -| Name | Definition | -+===================================+======================================================+ -| entityId | Id (URI) of the concerned entity | -+-----------------------------------+------------------------------------------------------+ -| attrId | Attribute name (Property or Relationship) | -+-----------------------------------+------------------------------------------------------+ -| instanceId | Id (URI) identifying a particular Attribute instance | -+-----------------------------------+------------------------------------------------------+ -::: - -### 6.22.3 Resource methods {#tabresource-methods-18 number="11.22.3"} - -#### 6.22.3.1 PATCH {#tabpatch-6 number="11.22.3.1"} - -This method is associated to the operation "Modify attribute instance from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.6.14](10-tabapi-operation-definition.md#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. The attribute name is the value of the resource URI variable *attrId*. The instance identifier is the value of the resource URI variable *instanceId*. [Figure 6.22.3.1‑1](11-tabapi-http-binding.md#Figure_6.22.3.1-1) shows the Modify Attribute instance interaction and [Table 6.22.3.1‑1](11-tabapi-http-binding.md#Table_6.22.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image116.png){style="width:4.19444in;height:1.95833in"} -::: - -::: {#Figure_6.22.3.1-1 .TF} -Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution interaction -::: - -::: {#Table_6.22.3.1-1 .TH} -Table 6.22.3.1-1: Modify Attribute instance from Temporal Evolution request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | EntityTemporal Fragment | 1 | EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced. | -+===============+======================================================================+=============+=====================================================+================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.22.3.2 DELETE {#tabdelete-8 number="11.22.3.2"} - -This method is associated to the operation "Delete Attribute instance from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by [clause 5.6.15](10-tabapi-operation-definition.md#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity). The Entity identifier is the value of the resource URI variable *entityId*. The Attribute name is the value of the resource URI variable *attrId*. The instance identifier is the value of the resource URI variable *instanceId*. [Figure 6.22.3.2‑1](11-tabapi-http-binding.md#Figure_6.22.3.2-1) shows the Delete Attribute instance interaction and [Table 6.22.3.2‑1](11-tabapi-http-binding.md#Table_6.22.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image117.png){style="width:4.38889in;height:1.45833in"} -::: - -::: {#Figure_6.22.3.2-1 .TF} -Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity interaction -::: - -::: {#Table_6.22.3.2-1 .TH} -Table 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.23 Resource: entityOperations/query {#tabresource-entityoperationsquery number="11.23"} - -### 6.23.1 Description {#tabdescription-81 number="11.23.1"} - -A sub-resource, pertaining to the *entityOperations/* resource, intended to enable querying for entities by means of a POST method. The behaviour of this clause mirrors the one in [clause 6.4.3.2](11-tabapi-http-binding.md#tabget), which performs the "Query Entity" operation (defined by [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) by means of a GET method. The reason to provide an alternative via POST is that, using GET: - -::: BL -a. The client may end up assembling very long URLs, due to the URI parameters for *id*, *q*‚ *type*, *attrs*, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length. -b. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode. -::: - -### 6.23.2 Resource definition {#tabresource-definition-19 number="11.23.2"} - -Resource URI: - -::: B1plus -- /entityOperations/query -::: - -### 6.23.3 Resource methods {#tabresource-methods-19 number="11.23.3"} - -#### 6.23.3.1 POST {#tabpost-11 number="11.23.3.1"} - -This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by [clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities). [Figure 6.23.3.1‑1](11-tabapi-http-binding.md#Figure_6.23.3.1-1) shows the operation interaction and [Table 6.23.3.1‑1](11-tabapi-http-binding.md#Table_6.23.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image118.png){style="width:3.41667in;height:5.16667in"} -::: - -::: {#Figure_6.23.3.1-1 .TF} -Figure 6.23.3.1-1: Query Entity via POST interaction -::: - -::: {#Table_6.23.3.1-1 .TH} -Table 6.23.3.1-1: Query Entity via POST request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Query | 1 | Payload body in the request contains a JSON-LD object which represents the query to be performed. | -+===============+======================================================================+=============+=========================================================+============================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Entity[] | 1 | 200 OK | [A r]{.ondemand_CHAR_name_Arial_size_9}[esponse body containing the query result as a list of Entities.]{.ondemand_CHAR_name_Arial_size_9} | -| | | | | | -| | | | 201 Created (in case an EntityMap has been (re)created) | The HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | GeoJSON FeatureCollection | 1 | 200 OK | If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned. | -| | | | | | -| | | | 201 Created (in case an EntityMap has been (re)created) | The HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Entity[] | 1 | 203 Non-Authoritative Information | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | -| | | | | | -| | | | | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.24 Resource: temporal/entityOperations/query {#tabresource-temporalentityoperationsquery number="11.24"} - -### 6.24.1 Description {#tabdescription-82 number="11.24.1"} - -A sub-resource, pertaining to the *temporal/entityOperations/* resource, intended to enable temporal querying for entities by means of a POST method. The behaviour of this clause mirrors the one in [clause 6.18.3.2](11-tabapi-http-binding.md#tabget-8), which performs the "Query [Temporal Evolution of Entities]{.HTML_Keyboard}" (defined by [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)) operation by means of a GET method. The reason to provide an alternative via POST is that, using GET: - -::: BL -a. The client may end up assembling very long URLs, due to the URI parameters for *id*, *q*‚ *type*, *attrs*, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length. -b. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode. -::: - -### 6.24.2 Resource definition {#tabresource-definition-20 number="11.24.2"} - -Resource URI: - -::: B1plus -- /temporal/entityOperations/query -::: - -### 6.24.3 Resource methods {#tabresource-methods-20 number="11.24.3"} - -#### 6.24.3.1 POST {#tabpost-12 number="11.24.3.1"} - -This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by [clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities). [Figure 6.24.3.1‑1](11-tabapi-http-binding.md#Figure_6.24.3.1-1) shows the operation interaction and [Table 6.24.3.1‑1](11-tabapi-http-binding.md#Table_6.24.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image119.png){style="width:3.41667in;height:2.97222in"} -::: - -::: {#Figure_6.24.3.1-1 .TF} -Figure 6.24.3.1-1: Temporal Query Entity via POST interaction -::: - -::: {#Table_6.24.3.1-1 .TH} -Table 6.24.3.1-1: Temporal Query Entity via POST request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Query | 1 | Payload body in the request contains a JSON-LD object which represents the query to be performed. | -+===============+======================================================================+=============+=========================================================+======================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTemporal[] | 1 | 200 OK | A response body containing the query result as a list of Entities. | -| | | | | | -| | | | 201 Created (in case an EntityMap has been (re)created) | The HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.25 Resource: types/ {#tabresource-types number="11.25"} - -### 6.25.1 Description {#tabdescription-83 number="11.25.1"} - -This resource represents the entity types available in an NGSI-LD system. - -### 6.25.2 Resource definition {#tabresource-definition-21 number="11.25.2"} - -Resource URI: - -::: B1plus -- /types/ -::: - -### 6.25.3 Resource methods {#tabresource-methods-21 number="11.25.3"} - -#### 6.25.3.1 GET {#tabget-10 number="11.25.3.1"} - -This method is associated to the operations "Retrieve Available Entity Types" and "Retrieve Details of Available Entity Types" (if the *details* parameter is set to *true*) and shall exhibit the behaviour defined by clauses [5.7.5](10-tabapi-operation-definition.md#tabretrieve-available-entity-types) and [5.7.6](10-tabapi-operation-definition.md#tabretrieve-details-of-available-entity-types) respectively. - -::: FL -![](./media/image120.png){style="width:3.80556in;height:2.65278in"} -::: - -::: {#Figure_6.25.3.1-1 .TF} -Figure 6.25.3.1-1: Retrieve Available Entity Types interaction -::: - -The request parameters that shall be supported are those defined in [Table 6.25.3.1‑1](11-tabapi-http-binding.md#Table_6.25.3.1-1) and [Table 6.25.3.1‑2](11-tabapi-http-binding.md#Table_6.25.3.1-2) describes the request body and possible responses. - -::: {#Table_6.25.3.1-1 .TH} -Table 6.25.3.1-1: Retrieve Available Entity Types URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+==================================================================================================================================================================================================================+ -| details | Boolean | 0..1 | If *true*, then detailed entity type information represented as an array with elements of the Entity Type data structure [(clause 5.2.25](10-tabapi-operation-definition.md#tabentitytype)) is to be returned. | -+-----------------+-----------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.25.3.1-2 .TH} -Table 6.25.3.1-2: Retrieve Available Entity Types request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+===================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTypeList | 1 | 200 OK | A response body containing the JSON-LD representation of the EntityTypeList [(clause 5.2.24](10-tabapi-operation-definition.md#tabentitytypelist)) is to be returned, unless *details=true* is specified. | -| +----------------------------------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityType[] | 1 | 200 OK | If *details=true* is specified, a response body containing a JSON-LD array with elements of the EntityType data structure [(clause 5.2.25](10-tabapi-operation-definition.md#tabentitytype)) is to be returned. | -| +----------------------------------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.26 Resource: types/{type} {#tabresource-typestype number="11.26"} - -### 6.26.1 Description {#tabdescription-84 number="11.26.1"} - -This resource represents the specified entity type for which entity instances are available in an NGSI-LD system. - -### 6.26.2 Resource definition {#tabresource-definition-22 number="11.26.2"} - -Resource URI: - -::: B1plus -- /types/{type} -::: - -Resource URI variables for this resource are defined in [Table 6.26.2‑1](11-tabapi-http-binding.md#Table_6.26.2-1). - -::: {#Table_6.26.2-1 .TH} -Table 6.26.2-1: URI variables -::: - -::: TAL -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Definition | -+===================================+=====================================================================================================================================================================================================================+ -| type | Name of the entity type for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD *\@context* provided. | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.26.3 Resource methods {#tabresource-methods-22 number="11.26.3"} - -#### 6.26.3.1 GET {#tabget-11 number="11.26.3.1"} - -This method is associated to the operation "Retrieve Available Entity Type Information" and shall exhibit the behaviour defined by [clause 5.7.7](10-tabapi-operation-definition.md#tabretrieve-available-entity-type-information). The entity type is the value of the resource URI variable "type". [Figure 6.26.3.1‑1](11-tabapi-http-binding.md#Figure_6.26.3.1-1) shows the retrieve available entity type interaction. - -::: FL -![](./media/image121.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.26.3.1-1 .TF} -Figure 6.26.3.1-1: Retrieve Available Entity Type interaction -::: - -[Table 6.26.3.1‑1](11-tabapi-http-binding.md#Table_6.26.3.1-1) describes the request body and possible responses. - -::: {#Table_6.26.3.1-1 .TH} -Table 6.26.3.1-1: Retrieve Available Entity Type request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=============================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityTypeInfo | 1 | 200 OK | A response body containing the JSON-LD representation of the detailed information about the available entity type. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an entity type not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.27 Resource: attributes/ {#tabresource-attributes number="11.27"} - -### 6.27.1 Description {#tabdescription-85 number="11.27.1"} - -This resource represents the attributes available in an NGSI-LD system. - -### 6.27.2 Resource definition {#tabresource-definition-23 number="11.27.2"} - -Resource URI: - -::: B1plus -- /attributes/ -::: - -### 6.27.3 Resource methods {#tabresource-methods-23 number="11.27.3"} - -#### 6.27.3.1 GET {#tabget-12 number="11.27.3.1"} - -This method is associated to the operations "Retrieve Available Attributes" and "Retrieve Details of Available Attributes" (if the *details* parameter is set to *true*) and shall exhibit the behaviour defined by clauses [5.7.8](10-tabapi-operation-definition.md#tabretrieve-available-attributes) and [5.7.9](10-tabapi-operation-definition.md#tabretrieve-details-of-available-attributes) respectively. - -::: FL -![](./media/image122.png){style="width:3.79167in;height:2.65278in"} -::: - -::: {#Figure_6.27.3.1-1 .TF} -Figure 6.27.3.1-1: Retrieve Available Attributes interaction -::: - -The request parameters that shall be supported are those defined in [Table 6.27.3.1‑1](11-tabapi-http-binding.md#Table_6.27.3.1-1) and [Table 6.27.3.1‑2](11-tabapi-http-binding.md#Table_6.27.3.1-2) describes the request body and possible responses. - -::: {#Table_6.27.3.1-1 .TH} -Table 6.27.3.1-1: Retrieve Available Attributes URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+=============================================================================================================================================================================================================+ -| details | Boolean | 0..1 | If *true*, then detailed attribute information represented as an array with elements of the Attribute data structure [(clause 5.2.28](10-tabapi-operation-definition.md#tabattribute)) is to be returned. | -+-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.27.3.1-2 .TH} -Table 6.27.3.1-2: Retrieve Available Attributes request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+=================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | AttributeList | 1 | 200 OK | A response body containing the JSON-LD representation of the AttributeList [(clause 5.2.27](10-tabapi-operation-definition.md#tabattributelist)) is to be returned, unless *details=true* is specified. | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Attribute[] | 1 | 200 OK | If *details=true* is specified, a response body containing a JSON-LD array with elements of the Attribute data structure [(clause 5.2.28](10-tabapi-operation-definition.md#tabattribute)) is to be returned. | -| +----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.28 Resource: attributes/{attrId} {#tabresource-attributesattrid number="11.28"} - -### 6.28.1 Description {#tabdescription-86 number="11.28.1"} - -This resource represents the specified attribute that belongs to entity instances existing within the NGSI-LD system. - -### 6.28.2 Resource definition {#tabresource-definition-24 number="11.28.2"} - -Resource URI: - -::: B1plus -- /attributes/{attrId} -::: - -Resource URI variables for this resource are defined in [Table 6.28.2‑1](11-tabapi-http-binding.md#Table_6.28.2-1). - -::: {#Table_6.28.2-1 .TH} -Table 6.28.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Definition | -+===================================+===================================================================================================================================================================================================================+ -| attrId | Name of the attribute for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD *\@context* provided. | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.28.3 Resource methods {#tabresource-methods-24 number="11.28.3"} - -#### 6.28.3.1 GET {#tabget-13 number="11.28.3.1"} - -This method is associated to the operation "Retrieve Available Attribute Information" and shall exhibit the behaviour defined by [clause 5.7.10](10-tabapi-operation-definition.md#tabretrieve-available-attribute-information). The attribute is the value of the resource URI variable "attrId". [Figure 6.28.3.1‑1](11-tabapi-http-binding.md#Figure_6.28.3.1-1) shows the retrieve available attribute information interaction. - -::: FL -![](./media/image123.png){style="width:3.40278in;height:1.84722in"} -::: - -::: {#Figure_6.28.3.1-1 .TF} -Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction -::: - -[Table 6.28.3.1‑1](11-tabapi-http-binding.md#Table_6.28.3.1-1) describes the request body and possible responses. - -::: {#Table_6.28.3.1-1 .TH} -Table 6.28.3.1-1: Retrieve Available Attribute Information request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Attribute | 1 | 200 OK | A response body containing the JSON-LD representation of the detailed information about the available attribute. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an attribute name not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.29 Resource: jsonldContexts/ {#tabresource-jsonldcontexts number="11.29"} - -### 6.29.1 Description {#tabdescription-87 number="11.29.1"} - -This resource represents the *\@contexts* known to an NGSI-LD system. - -### 6.29.2 Resource definition {#tabresource-definition-25 number="11.29.2"} - -Resource URI: - -::: B1plus -- /jsonldContexts/ -::: - -### 6.29.3 Resource methods {#tabresource-methods-25 number="11.29.3"} - -#### 6.29.3.1 POST {#tabpost-13 number="11.29.3.1"} - -This method is bound to the operation "Add *\@context*" and shall exhibit the behaviour defined by [clause 5.13.2](10-tabapi-operation-definition.md#tabadd-context), taking the *\@context* to be added from the HTTP request payload body. [Figure 6.29.3.1‑1](11-tabapi-http-binding.md#Figure_6.29.3.1-1) shows the Add *\@context* interaction and [Table 6.29.3.1‑1](11-tabapi-http-binding.md#Table_6.29.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image124.png){style="width:3.40278in;height:1.97222in"} -::: - -::: {#Figure_6.29.3.1-1 .TF} -Figure 6.29.3.1-1: Add \@context interaction -::: - -::: {#Table_6.29.3.1-1 .TH} -Table 6.29.3.1-1: Add \@context request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | JSON Object | 1 | Payload body in the request contains a JSON object that has a root node named *\@context*, which represents a JSON-LD "local context". | -+===============+======================================================================+=============+======================================================================+==========================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the local relative path of the added *\@context*. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.29.3.2 GET {#tabget-14 number="11.29.3.2"} - -This method is associated to the operation "List *\@contexts*" and shall exhibit the behaviour defined by [clause 5.13.3](10-tabapi-operation-definition.md#tablist-contexts), and it provides information about stored *\@contexts* as part of the HTTP response payload body. [Figure 6.29.3.2‑1](11-tabapi-http-binding.md#Figure_6.29.3.2-1) shows the List *\@contexts* interaction. - -::: FL -![](./media/image125.png){style="width:3.90278in;height:2.56944in"} -::: - -::: {#Figure_6.29.3.2-1 .TF} -Figure 6.29.3.2-1: List \@contexts interaction -::: - -The request parameters that shall be supported by implementations are those defined in [Table 6.29.3.2‑1](11-tabapi-http-binding.md#Table_6.29.3.2-1) and Table 6.29.3.2-2 describes the request body and possible responses. - -::: {#Table_6.29.3.2-1 .TH} -Table 6.29.3.2-1: List \@contexts URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+===========================================================================================================+ -| details | Boolean | 0..1 | Whether a list of URLs or a more detailed list of JSON Objects is requested. | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------+ -| kind | String | 0..1 | Can be either ["Cached"]{.HTML_Code}, ["Hosted"]{.HTML_Code}, or ["ImplicitlyCreated"]{.HTML_Code}. | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_6.29.3.2-2 .TH} -Table 6.29.3.2-2: List \@contexts request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+===============================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | String[] | 1 | 200 OK | A response body containing a list of URLs or a list of JSON Objects, as defined in [clause 5.13.3.5](10-tabapi-operation-definition.md#taboutput-data-47), representing metadata about stored *\@contexts*. | -| | | | | | -| | or | | | | -| | | | | | -| | JSON Object[] | | | | -| +----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.30 Resource: jsonldContexts/{contextId} {#tabresource-jsonldcontextscontextid number="11.30"} - -### 6.30.1 Description {#tabdescription-88 number="11.30.1"} - -This resource represents a JSON-LD *\@context* stored in the broker's internal *\@context* storage. - -### 6.30.2 Resource definition {#tabresource-definition-26 number="11.30.2"} - -Resource URI: - -::: B1plus -- /jsonldContexts/{contextId} -::: - -Resource URI variables for this resource are defined in [Table 6.30.2‑1](11-tabapi-http-binding.md#Table_6.30.2-1). - -::: {#Table_6.30.2-1 .TH} -Table 6.30.2-1: URI variables -::: - -::: TAL -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Definition | -+===================================+========================================================================================================================================================================================================+ -| contextId | Local identifier of the *\@context* to be managed (served or deleted). For *\@contexts* of kind ["Cached"]{.HTML_Code} this can also be the original URL the broker downloaded the *\@context* from. | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -### 6.30.3 Resource methods {#tabresource-methods-26 number="11.30.3"} - -#### 6.30.3.1 GET {#tabget-15 number="11.30.3.1"} - -This method is associated to the operation "Serve *\@context*" and shall exhibit the behaviour defined by [clause 5.13.4](10-tabapi-operation-definition.md#tabserve-context). The *\@context* identifier is the value of the resource URI variable "contextId". [Figure 6.30.3.1‑1](11-tabapi-http-binding.md#Figure_6.30.3.1-1) shows the HTTP Serve *\@context* interaction. - -::: FL -![](./media/image126.png){style="width:3.91667in;height:2.52778in"} -::: - -::: {#Figure_6.30.3.1-1 .TF} -Figure 6.30.3.1-1: Serve \@context interaction -::: - -The request parameters that shall be supported by implementations are those defined in [Table 6.30.3.1‑1](11-tabapi-http-binding.md#Table_6.30.3.1-1) and Table 6.30.3.1-2 describes the request body and possible responses. - -::: {#Table_6.30.3.1-1 .TH} -Table 6.30.3.1-1: Serve \@contexts URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+----------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+======================================================================+ -| details | Boolean | 0..1 | Whether the content of the *\@context* or its metadata is requested. | -+-----------------+-----------------+-----------------+----------------------------------------------------------------------+ -::: - -::: {#Table_6.30.3.1-2 .TH} -Table 6.30.3.1-2: Serve \@context request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+===================+==================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | {TAH} | If the parameter details are *false* or missing, response body contains a JSON object that has a root node named *\@context*, which represents a JSON-LD "local context". | -| | | | | | -| | JSON Object | 1 | 200 OK | If the parameter details are *true*, response body contains a JSON object as defined in [clause 5.13.4.5](10-tabapi-operation-definition.md#taboutput-data-48), which metadata of a JSON-LD "local context". | -| +----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAH} | {TAH} | {TAH} | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an *\@context* identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| +----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 422 Unprocessable | It is used when a client indicated an *\@context* of type ["Cached"]{.HTML_Code}, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.30.3.2 DELETE {#tabdelete-9 number="11.30.3.2"} - -This method is associated to the operation "Delete and Reload *\@context*" and shall exhibit the behaviour defined by [clause 5.13.5](10-tabapi-operation-definition.md#tabdelete-and-reload-context). The Entity identifier is the value of the resource URI variable "contextId". [Figure 6.30.3.2‑1](11-tabapi-http-binding.md#Figure_6.30.3.2-1) shows the delete entity interaction. The request parameters that shall be supported are those defined in [Table 6.30.3.2‑1](11-tabapi-http-binding.md#Table_6.30.3.2-1) and Table 6.30.3.2-2 describes the request body and possible responses. - -::: {#Table_6.30.3.2-1 .TH} -Table 6.30.3.2-1: Delete and Reload \@context URL parameters -::: - -::: TAL -+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+=================+=================+=================+=========================================================================================================================================================+ -| reload | Boolean | 0..1 | indicates to perform a download and replace of the *\@context*, as specified in [clause 5.13.5.4](10-tabapi-operation-definition.md#tabbehaviour-49). | -+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: FL -![](./media/image127.png){style="width:3.40278in;height:1.45833in"} -::: - -::: {#Figure_6.30.3.2-1 .TF} -Figure 6.30.3.2-1: Delete and Reload \@context interaction -::: - -::: {#Table_6.30.3.2-2 .TH} -Table 6.30.3.2-2: Delete and Reload \@context request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=====================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an *\@context* identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| +----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 504 Gateway Timeout | It is used when re-downloading fails. | -+---------------+----------------------------------------------------------------------+-------------+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.31 Resource: entityOperations/merge {#tabresource-entityoperationsmerge number="11.31"} - -### 6.31.1 Description {#tabdescription-89 number="11.31.1"} - -A sub-resource, pertaining to the *entityOperations*/ resource, intended to enable batch entity merge for the NGSI-LD API. - -### 6.31.2 Resource definition {#tabresource-definition-27 number="11.31.2"} - -Resource URI: - -::: B1plus -- /entityOperations/merge -::: - -### 6.31.3 Resource methods {#tabresource-methods-27 number="11.31.3"} - -#### 6.31.3.1 POST {#tabpost-14 number="11.31.3.1"} - -This method is associated to the operation "Batch Entity Merge" and shall exhibit the behaviour defined by [clause 5.6.20](10-tabapi-operation-definition.md#tabbatch-entity-merge). [Figure 6.31.3.1‑1](11-tabapi-http-binding.md#Figure_6.31.3.1-1) shows the operation interaction and [Table 6.31.3.1‑1](11-tabapi-http-binding.md#Table_6.31.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image128.png){style="width:3.94444in;height:2.56944in"} -::: - -::: {#Figure_6.31.3.1-1 .TF} -Figure 6.31.3.1-1: Batch Entity Merge interaction -::: - -::: {#Table_6.31.3.1-1 .TH} -Table 6.31.3.1-1: Batch Entity Merge request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Entity[] | 1 | Array of Entities to be merged. | -+===============+======================================================================+=============+==================+=============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Code | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | If all entities have been successfully merged, there is no payload body in the response. | -| +----------------------------------------------------------------------+-------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully merged entities, while the second array (*errors*) contains information about the error for each of the entities that could not be merged-patched. There is no restriction as to the order of the Entity IDs in the arrays. | -| | | | | | -| | | | | If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | -| | | | | | -| | | | | In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a *BatchOperationResult* structure. | -| | | | | | -| | | | | Errors can occur whenever a distributed operation is unsupported, fails or times out, see [clause 6.3.17](11-tabapi-http-binding.md#tabdistributed-operations-caching-and-timeout-behaviour). | -| +----------------------------------------------------------------------+-------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.32 Resource: entityMaps/{entityMapId} {#tabresource-entitymapsentitymapid number="11.32"} - -### 6.32.1 Description {#tabdescription-90 number="11.32.1"} - -This resource represents an EntityMap available in the broker's internal storage or memory. - -### 6.32.2 Resource definition {#tabresource-definition-28 number="11.32.2"} - -Resource URI: - -::: B1plus -- /entityMaps/{entityMapId} -::: - -Resource URI variables for this resource are defined in [Table 6.32.2‑1](11-tabapi-http-binding.md#Table_6.32.2-1). - -::: {#Table_6.32.2-1 .TH} -Table 6.32.2-1: URI variables -::: - -::: TAL -+-----------------------------------+----------------------------------------------------------------+ -| Name | Definition | -+===================================+================================================================+ -| entityMapId | Id (URI) of the EntityMap to be retrieved, updated or deleted. | -+-----------------------------------+----------------------------------------------------------------+ -::: - -### 6.32.3 Resource methods {#tabresource-methods-28 number="11.32.3"} - -#### 6.32.3.1 GET {#tabget-16 number="11.32.3.1"} - -This method is associated to the operation "Retrieve EntityMap" and shall exhibit the behaviour defined by [clause 5.14.1](10-tabapi-operation-definition.md#tabretrieve-entitymap). The EntityMap identifier is the value of the resource URI variable "entityMapId". [Figure 6.32.3.1‑1](11-tabapi-http-binding.md#Figure_6.32.3.1-1) shows the Retrieve EntityMap interaction and [Table 6.32.3.1‑1](11-tabapi-http-binding.md#Table_6.32.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image129.png){style="width:3.41667in;height:1.875in"} -::: - -::: {#Figure_6.32.3.1-1 .TF} -Figure 6.32.3.1-1: Retrieve EntityMap -::: - -::: {#Table_6.32.3.1-1 .TH} -Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses -::: - -::: TAH -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+======================================================================================================================================================+ -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityMap | 1 | 200 OK | {TAL} | -| | | | | | -| | | | | A response body containing the JSON-LD representation of the target entity. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | {TAL} | -| | | | | | -| | | | | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.32.3.2 PATCH {#tabpatch-7 number="11.32.3.2"} - -This method is associated to the operation "Update EntityMap" and shall exhibit the behaviour defined by [clause 5.14.2](10-tabapi-operation-definition.md#tabupdate-entitymap). The EntityMap identifier is the value of the resource URI variable "entityMapId". [Figure 6.32.3.2‑1](11-tabapi-http-binding.md#Figure_6.32.3.2-1) shows the Update EntityMap interaction and [Table 6.32.3.2‑1](11-tabapi-http-binding.md#Table_6.32.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image130.png){style="width:3.41667in;height:1.875in"} -::: - -::: {#Figure_6.32.3.2-1 .TF} -Figure 6.32.3.2-1: Update EntityMap -::: - -::: {#Table_6.32.3.2-1 .TH} -Table 6.32.3.2-1: Update EntityMap request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | EntityMap Fragment | 1 | Payload body in the request contains a JSON-LD object which represents the EntityMap fragment with which the EntityMap is to be updated. | -+===============+======================================================================+=============+======================================================================+======================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.32.3.3 DELETE {#tabdelete-10 number="11.32.3.3"} - -This method is associated to the operation "Delete EntityMap" and shall exhibit the behaviour defined by [clause 5.14.3](10-tabapi-operation-definition.md#tabdelete-entitymap). The Entity identifier is the value of the resource URI variable "contextId". [Figure 6.32.3.3‑1](11-tabapi-http-binding.md#Figure_6.32.3.3-1) shows the delete entity interaction and [Table 6.32.3.3‑1](11-tabapi-http-binding.md#Table_6.32.3.3-1) describes the request body and possible responses. - -::: FL -![](./media/image131.png){style="width:3.44444in;height:1.48611in"} -::: - -::: {#Figure_6.32.3.3-1 .TF} -Figure 6.32.3.3-1: Delete and Reload \@context interaction -::: - -::: {#Table_6.32.3.3-1 .TH} -Table 6.32.3.3-1: Delete EntityMap request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an *\@context* identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.33 Resource: info/sourceIdentity {#tabresource-infosourceidentity number="11.33"} - -### 6.33.1 Description {#tabdescription-91 number="11.33.1"} - -This resource represents identity information about the [Context Source]{.HTML_Keyboard} itself. - -### 6.33.2 Resource definition {#tabresource-definition-29 number="11.33.2"} - -Resource URI: - -::: B1plus -- /info/sourceIdentity -::: - -### 6.33.3 Resource methods {#tabresource-methods-29 number="11.33.3"} - -#### 6.33.3.1 GET {#tabget-17 number="11.33.3.1"} - -This method is associated to the operation "Retrieve Context Source Identity Information" and shall exhibit the behaviour defined by [clause 5.15.1](10-tabapi-operation-definition.md#tabretrieve-context-source-identity-information). [Figure 6.33.3.1‑1](11-tabapi-http-binding.md#Figure_6.33.3.1-1) shows the Retrieve Context Source Identity Information interaction and [Table 6.33.3.1‑1](11-tabapi-http-binding.md#Table_6.33.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image132.png){style="width:3.43056in;height:1.875in"} -::: - -::: {#Figure_6.33.3.1-1 .TF} -Figure 6.33.3.1-1: Retrieve Context Source Identity Information -::: - -::: {#Table_6.33.3.1-1 .TH} -Table 6.33.3.1-1: Retrieve Context Source Identity Information request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=====================+=========================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ContextSourceIdentity | 1 | 200 No Content | A response body containing the JSON-LD representation of the Context Source Identity Information. | -| +----------------------------------------------------------------------+-------------+---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 501 Not Implemented | It is used by [Context Sources]{.HTML_Keyboard} to indicate that retrieval of the Context Source information is unsupported see [clause 5.15.1.4](10-tabapi-operation-definition.md#tabbehaviour-55). | -+---------------+----------------------------------------------------------------------+-------------+---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.34 Resource: entityMaps {#tabresource-entitymaps number="11.34"} - -### 6.34.1 Description {#tabdescription-92 number="11.34.1"} - -This resource represents the Entity maps in an NGSI-LD system. - -### 6.34.2 Resource definition {#tabresource-definition-30 number="11.34.2"} - -Resource URI: - -::: B1plus -- /entityMaps/ -::: - -### 6.34.3 Resource methods {#tabresource-methods-30 number="11.34.3"} - -#### 6.34.3.1 GET {#tabget-18 number="11.34.3.1"} - -This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by [clause 5.14.4](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-entities), providing an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Create EntityMap for Query Entities " operations via POST is defined in [clause 6.34.3.2](11-tabapi-http-binding.md#tabpost-15). [Figure 6.34.3.1‑1](11-tabapi-http-binding.md#Figure_6.34.3.1-1) shows the Create EntityMap for Query Entities interaction. - -::: FL -![](./media/image133.png){style="width:3.41667in;height:2.83333in"} -::: - -::: {#Figure_6.34.3.1-1 .TF} -Figure 6.34.3.1-1: Create EntityMap for Query Entities interaction -::: - -The URL parameters that shall be supported by implementations are the same as those for Query Entities and can be found in [Table 6.4.3.2‑1](11-tabapi-http-binding.md#Table_6.4.3.2-1). [Table 6.34.3.1‑1](11-tabapi-http-binding.md#Table_6.34.3.1-1) describes the request body and possible responses. - -::: {#Table_6.34.3.1-1 .TH} -Table 6.34.3.1-1: Create EntityMap for Query Entities request body and possible responses -::: - -::: TAL -+----------------------------------------------------------------------+-------------+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -+======================================================================+=============+===================================+============================================================================================================================================================================================================================================================================+===============+ -| N/A | N/A | | | | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -| EntityMap | 1 | 201 Created | A response body containing the entityMap with the identifiers of the Entities matching the query. | | -| | | | | | -| | | | The HTTP response shall include an ["NGSILD-EntityMap"]{.HTML_Code} HTTP header that contains the resource URI of the EntityMap resource created in the operation. | | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -| EntityMap | 1 | 203 Non-Authoritative Information | As above, but returning an **altered** **response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads). | | -| | | | | | -| | | | The response shall also include a ["Preference-Applied"]{.HTML_Code} HTTP header set to ["ngsi-ld="]{.HTML_Code}. | | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -| ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | | -| | | | | | -| | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -| ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 501 Not Implemented | It is used by Registered [Context Sources]{.HTML_Keyboard} to indicate that the data format of the request is unsupported see [clause 6.3.7](11-tabapi-http-binding.md#tabrepresentation-of-entities). | | -+----------------------------------------------------------------------+-------------+-----------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+ -::: - -#### 6.34.3.2 POST {#tabpost-15 number="11.34.3.2"} - -This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by [clause 5.14.4](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-entities). [Figure 6.34.3.2‑1](11-tabapi-http-binding.md#Figure_6.34.3.2-1) shows the operation interaction and [Table 6.34.3.2‑1](11-tabapi-http-binding.md#Table_6.34.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image134.png){style="width:3.40278in;height:1.83333in"} -::: - -::: {#Figure_6.34.3.2-1 .TF} -Figure 6.34.3.2-1: Create EntityMap for Query Entities via POST interaction -::: - -::: {#Table_6.34.3.2-1 .TH} -Table 6.34.3.2-1: Create EntityMap for Query Entities via POST request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Query | 1 | Payload body in the request contains a JSON-LD object which represents the query to be performed. | -+===============+======================================================================+=============+===================================================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityMap | 1 | 201 Created | A response body containing the entityMap with the identifiers of the Entities matching the query. | -| | | | | | -| | | | | The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.35 Resource: temporal/entityMaps {#tabresource-temporalentitymaps number="11.35"} - -### 6.35.1 Description {#tabdescription-93 number="11.35.1"} - -This resource is used for creating entityMaps based on temporal queries in an NGSI-LD system. - -### 6.35.2 Resource definition {#tabresource-definition-31 number="11.35.2"} - -Resource URI: - -::: B1plus -- /temporal/entityMaps/ -::: - -### 6.35.3 Resource methods {#tabresource-methods-31 number="11.35.3"} - -#### 6.35.3.1 GET {#tabget-19 number="11.35.3.1"} - -This method is associated to the operation "Create EntityMap for Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by [clause 5.14.5](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-temporal-evolution-of-entities), an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Create EntityMap for Query Temporal Evolution of Entities" operations via POST is defined in [clause 6.35.3.2](11-tabapi-http-binding.md#tabpost-16). [Figure 6.35.3.1‑1](11-tabapi-http-binding.md#Figure_6.35.3.1-1) shows this interaction. - -::: FL -![](./media/image135.png){style="width:3.41667in;height:1.94444in"} -::: - -::: {#Figure_6.35.3.1-1 .TF} -Figure 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities interaction -::: - -The URL parameters that shall be supported by implementations are the same as those for Query Temporal Evolution of Entities and can be found in [Table 6.18.3.2‑1](11-tabapi-http-binding.md#Table_6.18.3.2-1). [Table 6.35.3.1‑1](11-tabapi-http-binding.md#Table_6.35.3.1-1) describes the request body and possible responses. - -::: {#Table_6.35.3.1-1 .TH} -Table 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityMap | 1 | 201 Created | A response body containing the entityMap with the identifiers of the Entities matching the query. | -| | | | | | -| | | | | The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.35.3.2 POST {#tabpost-16 number="11.35.3.2"} - -This method is associated to the operation "Create EntityMap for Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by [clause 5.14.5](10-tabapi-operation-definition.md#tabcreate-entitymap-for-query-temporal-evolution-of-entities). [Figure 6.35.3.2‑1](11-tabapi-http-binding.md#Figure_6.35.3.2-1) shows the operation interaction and [Table 6.35.3.2‑1](11-tabapi-http-binding.md#Table_6.35.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image136.png){style="width:3.40278in;height:1.83333in"} -::: - -::: {#Figure_6.35.3.2-1 .TF} -Figure 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST interaction -::: - -::: {#Table_6.35.3.2-1 .TH} -Table 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Query | 1 | Payload body in the request contains a JSON-LD object which represents the query to be performed. | -+===============+======================================================================+=============+===================================================+========================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | EntityMap | 1 | 201 Created | A response body containing the entityMap with the identifiers of the Entities matching the query. | -| | | | | | -| | | | | The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation. | -| +----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.36 Resource: snapshots {#tabresource-snapshots number="11.36"} - -### 6.36.1 Description {#tabdescription-94 number="11.36.1"} - -This resource represents Snapshots available in an NGSI-LD system. - -### 6.36.2 Resource definition {#tabresource-definition-32 number="11.36.2"} - -Resource URI: - -::: B1plus -- /snapshots/ -::: - -### 6.36.3 Resource methods {#tabresource-methods-32 number="11.36.3"} - -#### 6.36.3.1 POST {#tabpost-17 number="11.36.3.1"} - -This method is associated to the operation "Create Snapshot" and shall exhibit the behaviour defined by [clause 5.16.1](10-tabapi-operation-definition.md#tabcreate-snapshot). [Figure 6.36.3.1‑1](11-tabapi-http-binding.md#Figure_6.36.3.1-1) shows the operation interaction and [Table 6.36.3.1‑1](11-tabapi-http-binding.md#Table_6.36.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image137.png){style="width:3.41667in;height:1.83333in"} -::: - -::: {#Figure_6.36.3.1-1 .TF} -Figure 6.36.3.1-1: Create Snapshot interaction -::: - -::: {#Table_6.36.3.1-1 .TH} -Table 6.36.3.1-1: Create Snapshot request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Snapshot | 1 | Payload body in the request contains a JSON-LD object which represents parameters for the snapshot to be created. | -+===============+======================================================================+=============+===========================================================+======================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the created snapshot. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that a Snapshot having the Snapshot identifier included in the request body already exists, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.36.3.2 DELETE {#tabdelete-11 number="11.36.3.2"} - -This method is associated to the operation "Purge Snapshots" and shall exhibit the behaviour defined by [clause 5.16.7](10-tabapi-operation-definition.md#tabpurge-snapshots). [Figure 6.36.3.2‑1](11-tabapi-http-binding.md#Figure_6.36.3.2-1) shows the Purge Snapshot interaction. - -::: FL -![](./media/image138.png){style="width:3.80556in;height:2.01389in"} -::: - -::: {#Figure_6.36.3.2-1 .TF} -Figure 6.36.3.2-1: Purge Snapshots interaction -::: - -The URL parameters that shall be supported by implementations are those defined in [Table 6.36.3.2‑1](11-tabapi-http-binding.md#Table_6.36.3.2-1) and Table 6.36.3.2-2 describes the request body and possible responses. - -::: {#Table_6.36.3.2-1 .TH} -Table 6.36.3.2-1: Purge Snapshots URL parameters -::: - -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Data Type | Cardinality | Remarks | -+-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | -| q | String | 1 | Query as per [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language), restricted to members of the Snapshot data type. | -+=================+=================+=================+===========================================================================================================================================================+ - -::: {#Table_6.36.3.2-2 .TH} -Table 6.36.3.2-2: Purge Snapshots request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+==================+==============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | BatchOperationResult | 1 | 207 Multi-Status | If some or all of the Snapshots have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a *BatchOperationResult* structure. It contains two arrays. The first array (*success*) contains the URIs of the successfully deleted Snapshots, while the second array (*errors*) contains information about the error for each of the Snapshots that could not be deleted. There is no restriction as to the order of the Snapshots IDs in the arrays. | -| +----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a filter not matching any Snapshots, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.37 Resource: snapshots/{snapshotId} {#tabresource-snapshotssnapshotid number="11.37"} - -### 6.37.1 Description {#tabdescription-95 number="11.37.1"} - -This resource represents a snapshot in an NGSI-LD system. - -### 6.37.2 Resource definition {#tabresource-definition-33 number="11.37.2"} - -Resource URI: - -::: B1plus -- /snapshots/{snapshotId} -::: - -Resource URI variables for this resource are defined in [Table 6.37.2‑1](11-tabapi-http-binding.md#Table_6.37.2-1). - -::: {#Table_6.37.2-1 .TH} -Table 6.37.2-1: URI variables -::: - -::: TAL -+-----------------------------------+-----------------------------------------------------------------------------------------------------+ -| Name | Definition | -+===================================+=====================================================================================================+ -| snapshotId | Id (URI) of the Snapshot whose status is to be retrieved or updated, or the Snapshot to be deleted. | -+-----------------------------------+-----------------------------------------------------------------------------------------------------+ -::: - -### 6.37.3 Resource methods {#tabresource-methods-33 number="11.37.3"} - -#### 6.37.3.1 GET {#tabget-20 number="11.37.3.1"} - -This method is associated to the operation "Retrieve Snapshot Status" and shall exhibit the behaviour defined by [clause 5.16.3](10-tabapi-operation-definition.md#tabretrieve-snapshot-status). The Snapshot identifier is the value of the resource URI variable "snapshotId". [Figure 6.37.3.1‑1](11-tabapi-http-binding.md#Figure_6.37.3.1-1) shows the Retrieve Snapshot Status interaction and [Table 6.37.3.1‑1](11-tabapi-http-binding.md#Table_6.37.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image139.png){style="width:3.41667in;height:1.83333in"} -::: - -::: {#Figure_6.37.3.1-1 .TF} -Figure 6.37.3.1-1: Retrieve Snapshot Status interaction -::: - -::: {#Table_6.37.3.1-1 .TH} -Table 6.37.3.1-1: Retrieve Snapshot Status request body and possible responses -::: - -::: TAH -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+======================================================================================================================================================+ -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Snapshot | 1 | 200 OK | {TAL} | -| | | | | | -| | | | | A response body containing the JSON-LD representation of the target Snapshot status. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | {TAL} | -| | | | | | -| | | | | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | {TAL} | -| | | | | | -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.37.3.2 PATCH {#tabpatch-8 number="11.37.3.2"} - -This method is associated to the operation "Update Snapshot Status" and shall exhibit the behaviour defined by [clause 5.16.4](10-tabapi-operation-definition.md#tabupdate-snapshot-status). The Snapshot identifier is the value of the resource URI variable "snapshotId". [Figure 6.37.3.2‑1](11-tabapi-http-binding.md#Figure_6.37.3.2-1) shows the Update Snapshot Status interaction and [Table 6.37.3.2‑1](11-tabapi-http-binding.md#Table_6.37.3.2-1) describes the request body and possible responses. - -::: FL -![](./media/image140.png){style="width:3.41667in;height:2.04167in"} -::: - -::: {#Figure_6.37.3.2-1 .TF} -Figure 6.37.3.2-1: Update Snapshot Status interaction -::: - -::: {#Table_6.37.3.2-1 .TH} -Table 6.37.3.2-1: Update Snapshot Status request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Snapshot Fragment | 1 | Payload body in the request contains a JSON-LD object which represents the Snapshot fragment with which the Snapshot status is to be updated. | -+===============+======================================================================+=============+=========================================================================+======================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | Snapshot | 1 | 200 OK | A response body containing the JSON-LD representation of the updated Snapshot status. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided an EntityMap identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -#### 6.37.3.3 DELETE {#tabdelete-12 number="11.37.3.3"} - -This method is associated to the operation "Delete Snapshot" and shall exhibit the behaviour defined by [clause 5.16.5](10-tabapi-operation-definition.md#tabdelete-snapshot). The Snapshot identifier is the value of the resource URI variable "snapshotId". [Figure 6.37.3.3‑1](11-tabapi-http-binding.md#Figure_6.37.3.3-1) shows the Delete Snapshot interaction and [Table 6.37.3.3‑1](11-tabapi-http-binding.md#Table_6.37.3.3-1) describes the request body and possible responses. - -::: FL -![](./media/image141.png){style="width:3.41667in;height:1.54167in"} -::: - -::: {#Figure_6.37.3.3-1 .TF} -Figure 6.37.3.3-1: Delete Snapshot interaction -::: - -::: {#Table_6.37.3.3-1 .TH} -Table 6.37.3.3-1: Delete Snapshot request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | | | -| | | | | | -| | N/A | N/A | | | -+===============+======================================================================+=============+=================+====================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 204 No Content | | -| +----------------------------------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a snapshot identifier not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -+---------------+----------------------------------------------------------------------+-------------+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -## 6.38 Resource: snapshots/{snapshotId}/clone {#tabresource-snapshotssnapshotidclone number="11.38"} - -### 6.38.1 Description {#tabdescription-96 number="11.38.1"} - -This resource enables the cloning of a snapshot in an NGSI-LD system. - -### 6.38.2 Resource definition {#tabresource-definition-34 number="11.38.2"} - -Resource URI: - -::: B1plus -- /snapshots/{snapshotId}/clone -::: - -Resource URI variables for this resource are defined in [Table 6.38.2‑1](11-tabapi-http-binding.md#Table_6.38.2-1). - -::: {#Table_6.38.2-1 .TH} -Table 6.38.2-1: URI variables -::: - -::: TAL -+-----------------------------------+----------------------------------------------------+ -| Name | Definition | -+===================================+====================================================+ -| snapshotId | Id (URI) of the Snapshot to be queried or deleted. | -+-----------------------------------+----------------------------------------------------+ -::: - -### 6.38.3 Resource methods {#tabresource-methods-34 number="11.38.3"} - -#### 6.38.3.1 POST {#tabpost-18 number="11.38.3.1"} - -This method is associated to the operation "Clone Snapshot" and shall exhibit the behaviour defined by [clause 5.16.2](10-tabapi-operation-definition.md#tabclone-snapshot). The Snapshot identifier is the value of the resource URI variable "snapshotId". [Figure 6.38.3.1‑1](11-tabapi-http-binding.md#Figure_6.38.3.1-1) shows the Clone Snapshot interaction and [Table 6.38.3.1‑1](11-tabapi-http-binding.md#Table_6.38.3.1-1) describes the request body and possible responses. - -::: FL -![](./media/image142.png){style="width:3.41667in;height:1.83333in"} -::: - -::: {#Figure_6.38.3.1-1 .TF} -Figure 6.38.3.1-1: Clone Snapshot interaction -::: - -::: {#Table_6.38.3.1-1 .TH} -Table 6.38.3.1-1: Clone Snapshot request body and possible responses -::: - -::: TAL -+---------------+----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Request Body | Data Type | Cardinality | Remarks | -| +----------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | {TAL} | {TAL} | {TAL} | -| | | | | -| | Snapshot | 1 | Payload body in the request contains a JSON-LD object which represents parameters for the cloned snapshot. | -+===============+======================================================================+=============+=======================================================+========================================================================================================================================================================================+ -| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | -| | | | | | -| Response Body | Data Type | Cardinality | Response Codes | Remarks | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | N/A | N/A | 201 Created | The HTTP response shall include a ["Location"]{.HTML_Code} HTTP header that contains the relative path of the cloned snapshot. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 400 Bad Request | It is used to indicate that the request or its content is incorrect, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 404 Not Found | It is used when a client provided a Snapshot identifier (URI) not known to the system, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| +----------------------------------------------------------------------+-------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | ProblemDetails (see IETF RFC 7807 [[10]](7-tabreferences.md#10)) | 1 | 409 Conflict | It is used to indicate that the Snapshot having the Snapshot identifier included in the request body already exists, see [clause 6.3.2](11-tabapi-http-binding.md#taberror-types-1). | -| | | | | | -| | | | | In the returned *ProblemDetails* structure, the *detail* attribute should convey more information about the error. | -+---------------+----------------------------------------------------------------------+-------------+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: diff --git a/API-md/12-tabapi-mqtt-notification-binding.md b/API-md/12-tabapi-mqtt-notification-binding.md deleted file mode 100644 index 1f9bcdd3566f33428ace17f7123adf3295618b5f..0000000000000000000000000000000000000000 --- a/API-md/12-tabapi-mqtt-notification-binding.md +++ /dev/null @@ -1,65 +0,0 @@ -# 7 API MQTT Notification Binding {#tabapi-mqtt-notification-binding number="12"} - -## 7.1 Introduction {#tabintroduction-23 number="12.1"} - -This clause defines the optional support of the NGSI-LD API for sending notifications via the MQTT protocol [[24]](7-tabreferences.md#24) and [[25]](7-tabreferences.md#25). The subscriptions are handled using the HTTP binding as described in [clause 6](11-tabapi-http-binding.md#tabapi-http-binding), but instead of an HTTP endpoint, an MQTT endpoint is provided. - -## 7.2 Notification behaviour {#tabnotification-behaviour-3 number="12.2"} - -In case a subscription received via HTTP specifies an MQTT endpoint in the "notification.endpoint.uri" member of the subscription structure (defined by clauses [5.2.12](10-tabapi-operation-definition.md#tabsubscription), [5.2.14](10-tabapi-operation-definition.md#tabnotificationparams) and [5.2.15](10-tabapi-operation-definition.md#tabendpoint)), and the MQTT notification binding is supported by the NGSI-LD implementation, notifications related to this subscription shall be sent via the MQTT protocol. - -The syntax of an MQTT endpoint URI is [mqtt[s]://[][:]@[:]/[/]\*]{.HTML_Code} and follows an existing convention for representing an MQTT endpoint as a URI [[i.19]](7-tabreferences.md#i.19). - -Username and password can be optionally specified as part of the endpoint URI. If the port is not explicitly specified, the default MQTT port is 1883 for MQTT over TCP and 8883 for mqtts, i.e. Secure MQTT over TLS. MQTT supports the structuring of topics as a hierarchy with any number of subtopic levels, which can be specified as part of the endpoint URI. - -In MQTT, all non-protocol information has to be included into the MQTT message. This means that the actual notification as specified in [clause 5.3.1](10-tabapi-operation-definition.md#tabnotification), as well as additional information like MIME type, possibly the link to the *\@context* and additional user-specified information, which in the HTTP case is provided as headers, has to be included into the MQTT message. The MQTT notification message shall be provided as a JSON Object with the two elements ["metadata"]{.HTML_Code} and ["body".]{.HTML_Code} The actual notification, as specified in [clause 5.3.1](10-tabapi-operation-definition.md#tabnotification) is the value of ["body"]{.HTML_Code}, whereas any additional information is provided as key-value pairs in ["metadata"]{.HTML_Code}. - -For the MQTT protocol, there are currently two versions supported, MQTTv3.1.1 [[24]](7-tabreferences.md#24) and MQTTv5.0 [[25]](7-tabreferences.md#25). Also, there are three levels of quality of service: - -::: B1plus -- at most once (0); -- at least once (1); and -- exactly once (2). -::: - -These can be specified in the subscription as part of the optional array of KeyValuePair type (defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) "notification.endpoint.notifierInfo". The MQTT protocol parameters can be found in [Table 7.2‑1](12-tabapi-mqtt-notification-binding.md#Table_7.2-1). If not present, the given default value is used. - -::: {#Table_7.2-1 .TH} -Table 7.2-1: Protocol parameters for MQTT in notifierInfo -::: - -::: TAL -+--------------+--------------------+-------------+-----------------------------------------+-----------------------------------------------------------------------------------+ -| Key | Possible Values | Default | Source | Description | -+==============+====================+=============+=========================================+===================================================================================+ -| MQTT-QoS | 0, 1, 2 | 0 | Subscription's *notification.endpoint* | MQTT Quality of service, at most once (0), at least once (1) and exactly once (2) | -| | | | | | -| | | | *.notifierInfo* | | -+--------------+--------------------+-------------+-----------------------------------------+-----------------------------------------------------------------------------------+ -| MQTT-Version | mqtt3.1.1, mqtt5.0 | mqtt5.0 | Subscription's *notification.endpoint* | Version of MQTT protocol | -| | | | | | -| | | | *.notifierInfo* | | -+--------------+--------------------+-------------+-----------------------------------------+-----------------------------------------------------------------------------------+ -::: - -The MIME type associated with the notification shall be ["application/json"]{.HTML_Code} by default. However, this can be changed to["]{.HTML_Code}[application/ld+json]{.HTML_Code}["]{.HTML_Code} by means of the "endpoint.accept" member. The MIME type is specified as Content-Type in the ["metadata"]{.HTML_Code} element of the MQTT message. If the target MIME type is ["application/json"]{.HTML_Code} then the reference to the JSON-LD *\@context* is provided as Link in the ["metadata"]{.HTML_Code} element of the MQTT message, following the specification of the HTTP Link header as mandated by the JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 (to the default JSON-LD *\@context* if none available). [Table 7.2‑2](12-tabapi-mqtt-notification-binding.md#Table_7.2-2) lists these "receiver side" metadata parameters. - -::: {#Table_7.2-2 .TH} -Table 7.2-2: Parameters for MQTT in "metadata" -::: - -::: TAL -+--------------+-------------------------------------------------------------------------------------------------------------------------+--------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ -| Key | Possible Values | Default | Source | Description | -+==============+=========================================================================================================================+======================================+============================================================================================================================================================================================================================+==================================================================================================+ -| Content-Type | ["application/json"]{.HTML_Code}, ["application/ld+json"]{.HTML_Code} | ["application/json"]{.HTML_Code} | Subscription's | MIME type of the notification included in the ["body"]{.HTML_Code} element of the MQTT message | -| | | | | | -| | | | *notification* | | -| | | | | | -| | | | *.endpoint.accept* | | -+--------------+-------------------------------------------------------------------------------------------------------------------------+--------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ -| Link | Same format as specified in JSON-LD specification [[2]](7-tabreferences.md#2), section 6.2 for the HTTP Link header | Link Header provided in Subscription | Contains the reference to the *\@context* in case Content-Type is ["application/json"]{.HTML_Code}. Example: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" | | -+--------------+-------------------------------------------------------------------------------------------------------------------------+--------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ -::: - -Additionally, if the optional array of KeyValuePair type (defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) *notification.endpoint.receiverInfo* of the subscription is present, then a new entry for each member named "key" of the key, value pairs that make up the array shall be generated and added to the ["metadata"]{.HTML_Code} element of the MQTT message. The content of each entry shall be set equal to the content of the corresponding "value" member of the *KeyValuePair*. diff --git a/API-md/13-annex-a-normative-ngsi-ld-identifier-considerations.md b/API-md/13-annex-a-normative-ngsi-ld-identifier-considerations.md deleted file mode 100644 index d81087cc05247d5489735439dbb4f3f4bab5294f..0000000000000000000000000000000000000000 --- a/API-md/13-annex-a-normative-ngsi-ld-identifier-considerations.md +++ /dev/null @@ -1,36 +0,0 @@ -# Annex A (normative): NGSI-LD identifier considerations {#annex-a-normative-ngsi-ld-identifier-considerations number="13"} - -## A.1 Introduction {#a.1tabintroduction number="13.1"} - -The purpose of identifiers is to allow uniquely identifying NGSI-LD elements (Entities, Context Subscriptions or [Context Source Registrations]{.HTML_Keyboard}) within an NGSI-LD system. This annex is intended to clarify the different issues around the design of identifiers in NGSI-LD. - -## A.2 Entity identifiers {#a.2tabentity-identifiers number="13.2"} - -In order to enable the participation of NGSI-LD in linked data scenarios, all Entities are identified by **URIs**. If those URIs are expected to participate in external linked data relationships they **should** be dereferenceable. - -It is noteworthy that the identifier from the point of view of NGSI-LD is different from the inherent identifier that a specific Entity may have. For instance, an NGSI-LD Entity of Type ["]{.HTML_Code}[Vehicle]{.HTML_Code}["]{.HTML_Code} may have a Property named *licencePlateNumber*, which it is actually a unique identifier from the point of view of the Entity domain, as it uniquely identifies the specific vehicle instance. However, from the point of view of the NGSI-LD system, it may have another identifier which might or might not include such licence plate number identifier. - -## A.3 NGSI-LD namespace {#a.3tabngsi-ld-namespace number="13.3"} - -NGSI-LD defines a specific URN [[9]](7-tabreferences.md#9) namespace intended to help API users to design readable, clean and simple identifiers. As it is based on URNs, the usage of this identification approach is not recommended when dereferenceable URIs are needed (fully-fledged linked data scenarios). - -The referred namespace is defined as follows (to be registered with IANA): - -::: B1plus -- namespace identifier: NID = ["ngsi-ld"]{.HTML_Code} -- namespace specific string: NSS = EntityTypeName [":"]{.HTML_Code} EntityIdentificationString -::: - -*EntityTypeName* shall be an Entity Type name which can be expanded to a URI as per the *\@context*. - -*EntityIdentificationString* shall be a string that allows uniquely identifying the subject Entity in combination with the other items being part of the NSS. - -::: EX -EXAMPLE: - -[urn:ngsi-ld:Person:28976543]{.HTML_Code} . -::: - -It is recommended that applications use this URN namespace when applicable. - -In general, the URN specification defines namespace equivalence in a case-insensitive manner, however it is assumed that context-broker implementations shall always use lowercase letters in namespaces where they have a choice in case, unless there is a strong reason otherwise. Restricting the namespace prefix to lower case [urn:ngsi-ld:]{.HTML_Code} can improve caching and retrieval, since this ensures since alphabetic characters within the namespace specific string are always consistent. diff --git a/API-md/14-annex-b-normative-core-ngsi-ld-context-definition.md b/API-md/14-annex-b-normative-core-ngsi-ld-context-definition.md deleted file mode 100644 index a803c54f2439f6e815266eb185b8dfc30fb1ecec..0000000000000000000000000000000000000000 --- a/API-md/14-annex-b-normative-core-ngsi-ld-context-definition.md +++ /dev/null @@ -1,453 +0,0 @@ -# Annex B (normative): Core NGSI-LD \@context definition {#annex-b-normative-core-ngsi-ld-context-definition number="14"} - -Below is the definition of the Core NGSI-LD *\@context* which shall be supported by implementations. - -Such definition has been tested using [[i.7]](7-tabreferences.md#i.7). - -``` json -{ -  "@context": { -    "@version": 1.1, -    "@protected": true, -    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", -    "geojson": "https://purl.org/geojson/vocab#", -    "id": "@id", -    "type": "@type", -    "Attribute": "ngsi-ld:Attribute", -    "AttributeList": "ngsi-ld:AttributeList", -    "ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity", -    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", -    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", -    "Date": "ngsi-ld:Date", -    "DateTime": "ngsi-ld:DateTime", -    "EntityType": "ngsi-ld:EntityType", -    "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", -    "EntityTypeList": "ngsi-ld:EntityTypeList", -    "ExecutionResultDetails": "ngsi-ld:ExecutionResultDetails", -    "Feature": "geojson:Feature", -    "FeatureCollection": "geojson:FeatureCollection", -    "GeoProperty": "ngsi-ld:GeoProperty", -    "GeometryCollection": "geojson:GeometryCollection", -    "JsonProperty": "ngsi-ld:JsonProperty", -    "LanguageProperty": "ngsi-ld:LanguageProperty", -    "LineString": "geojson:LineString", -    "ListProperty": "ngsi-ld:ListProperty", -    "ListRelationship": "ngsi-ld:ListRelationship", -    "MultiLineString": "geojson:MultiLineString", -    "MultiPoint": "geojson:MultiPoint", -    "MultiPolygon": "geojson:MultiPolygon", -    "Notification": "ngsi-ld:Notification", -    "Point": "geojson:Point", -    "Polygon": "geojson:Polygon", -    "Property": "ngsi-ld:Property", -    "Relationship": "ngsi-ld:Relationship", -    "Snapshot": "ngsi-ld:Snapshot", -    "SnapshotNotification": "ngsi-ld:SnapshotNotification", -    "Subscription": "ngsi-ld:Subscription", -    "TemporalProperty": "ngsi-ld:TemporalProperty", -    "Time": "ngsi-ld:Time", -    "VocabProperty": "ngsi-ld:VocabProperty", -    "accept": "ngsi-ld:accept", -    "aggrParams": "ngsi-ld:aggrParams", -    "aggrMethods": "ngsi-ld:aggrMethods", -    "aggrPeriodDuration": "ngsi-ld:aggrPeriodDuration", -    "attributeCount": "attributeCount", -    "attributeDetails": "attributeDetails", -    "attributeList": { -      "@id": "ngsi-ld:attributeList", -      "@type": "@vocab" -    }, -    "attributeName": { -      "@id": "ngsi-ld:attributeName", -      "@type": "@vocab" -    }, -    "attributeNames": { -      "@id": "ngsi-ld:attributeNames", -      "@type": "@vocab" -    }, -    "attributeTypes": { -      "@id": "ngsi-ld:attributeTypes", -      "@type": "@vocab" -    }, -    "attributes": { -      "@id": "ngsi-ld:attributes", -      "@type": "@vocab" -    }, -    "attrs": "ngsi-ld:attrs", -    "avg": { -      "@id": "ngsi-ld:avg", -      "@container": "@list" -    }, -    "bbox": { -      "@container": "@list", -      "@id": "geojson:bbox" -    }, -    "cacheDuration": "ngsi-ld:cacheDuration", -    "collation": "ngsi-ld:collation", -    "containedBy": "ngsi-ld:isContainedBy", -    "contextSourceAlias": "ngsi-ld:contextSourceAlias", -    "contextSourceExtras": { -      "@id": "ngsi-ld:contextSourceExtras", -      "@type": "@json" -    }, -    "contextSourceInfo": "ngsi-ld:contextSourceInfo", -    "contextSourceTimeAt": { -      "@id": "ngsi-ld:contextSourceTimeAt", -      "@type": "DateTime" -    },  -    "contextSourceUptime": "ngsi-ld:contextSourceUptime", -    "cooldown": "ngsi-ld:cooldown", -    "coordinates": { -      "@container": "@list", -      "@id": "geojson:coordinates" -    }, -    "createdAt": { -      "@id": "ngsi-ld:createdAt", -      "@type": "DateTime" -    }, -    "csf": "ngsi-ld:csf", -"data": "ngsi-ld:data", -"dataset": { -"@id": "ngsi-ld:hasDataset", -      "@container": "@index" -}, -"datasetId": { -"@id": "ngsi-ld:datasetId", -"@type": "@id" -    }, -    "deletedAt": { -      "@id": "ngsi-ld:deletedAt", -      "@type": "DateTime" -    },  -    "description": "http://purl.org/dc/terms/description", -    "detail": "ngsi-ld:detail", -    "distinctCount": { -      "@id": "ngsi-ld:distinctCount", -      "@container": "@list" -    }, -    "endAt": { -      "@id": "ngsi-ld:endAt", -      "@type": "DateTime" -    }, -    "endTimeAt": { -      "@id": "ngsi-ld:endTimeAt", -      "@type": "DateTime" -    }, -    "endpoint": "ngsi-ld:endpoint", -    "entities": "ngsi-ld:entities", -    "entity": "ngsi-ld:entity", -    "entityCount": "ngsi-ld:entityCount", -    "entityId": { -      "@id": "ngsi-ld:entityId", -      "@type": "@id" -    }, -    "entityList": { -      "@id": "ngsi-ld:entityList", -      "@container": "@list" -    }, -    "entityMap": "ngsi-ld:hasEntityMap", -    "error": "ngsi-ld:error", -    "errors": "ngsi-ld:errors", -    "expandValues": "ngsi-ld:expandValues", -    "expiresAt": { -      "@id": "ngsi-ld:expiresAt", -      "@type": "DateTime" -    }, -    "features": { -      "@container": "@set", -      "@id": "geojson:features" -    }, -    "format": "ngsi-ld:format", -    "geoQ": "ngsi-ld:geoQ", -    "geometry": "geojson:geometry", -    "geoproperty": "ngsi-ld:geoproperty", -    "georel": "ngsi-ld:georel", -    "idPattern": "ngsi-ld:idPattern", -    "information": "ngsi-ld:information", -    "instanceId": { -      "@id": "ngsi-ld:instanceId", -      "@type": "@id" -    }, -    "isActive": "ngsi-ld:isActive", -    "join": "ngsi-ld:join", -    "joinLevel": "ngsi-ld:hasJoinLevel", -    "json": { -      "@id": "ngsi-ld:hasJSON", "@type": "@json" -    }, -    "jsonKeys": "ngsi-ld:jsonKeys", -    "jsons": { -      "@id": "ngsi-ld:jsons", -      "@container": "@list" -    }, -    "key": "ngsi-ld:hasKey", -    "lang": "ngsi-ld:lang", -    "languageMap": { -      "@id": "ngsi-ld:hasLanguageMap", -      "@container": "@language" -    }, -    "languageMaps": { -      "@id": "ngsi-ld:hasLanguageMaps", -      "@container": "@list" -    }, -    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString", -    "lastFailure": { -      "@id": "ngsi-ld:lastFailure", -      "@type": "DateTime" -    }, -    "lastNotification": { -      "@id": "ngsi-ld:lastNotification", -      "@type": "DateTime" -    }, -    "lastSuccess": { -      "@id": "ngsi-ld:lastSuccess", -      "@type": "DateTime" -    }, -    "lastUsedAt": { -      "@id": "ngsi-ld:lastUsedAt", -      "@type": "DateTime" -    }, -    "linkedMaps": "ngsi-ld:linkedMaps", -    "localOnly": "ngsi-ld:localOnly", -    "location": "ngsi-ld:location", -    "management": "ngsi-ld:management", -    "managementInterval": "ngsi-ld:managementInterval", -    "max": { -      "@id": "ngsi-ld:max", -      "@container": "@list" -    }, -    "min": { -      "@id": "ngsi-ld:min", -      "@container": "@list" -    }, -    "mode": "ngsi-ld:mode", -    "modifiedAt": { -      "@id": "ngsi-ld:modifiedAt", -      "@type": "DateTime" -    }, -    "ngsildproof": { -      "@id": "ngsi-ld:ngsildproof", -      "@context": [{ -        "entityIdSealed": "ngsi-ld:entityIdSealed", -        "entityTypeSealed": { -          "@id": "ngsi-ld:entityTypeSealed", -          "@type": "@vocab" -        } -      }, -      "https://w3id.org/security/data-integrity/v2" -      ] -    }, -    "notification": "ngsi-ld:notification", -    "notificationTrigger": "ngsi-ld:notificationTrigger", -    "notifiedAt": { -      "@id": "ngsi-ld:notifiedAt", -      "@type": "DateTime" -    }, -    "notifierInfo": "ngsi-ld:notifierInfo", -    "notUpdated": "ngsi-ld:notUpdated", -    "object": { -      "@id": "ngsi-ld:hasObject", -      "@type": "@id" -    }, -    "objectList": { -      "@id": "ngsi-ld:hasObjectList", -      "@container": "@list" -    }, -    "objectLists": { -      "@id": "ngsi-ld:hasObjectLists", -      "@container": "@list" -    }, -    "objects": { -      "@id": "ngsi-ld:hasObjects", -      "@container": "@list" -    }, -    "objectType": { -      "@id": "ngsi-ld:hasObjectType", -      "@type": "@vocab" -    }, -    "observationInterval": "ngsi-ld:observationInterval", -    "observationSpace": "ngsi-ld:observationSpace", -    "observedAt": { -      "@id": "ngsi-ld:observedAt", -      "@type": "DateTime" -    }, -    "omit": "ngsi-ld:omit", -    "operations": "ngsi-ld:operations", -    "operationSpace": "ngsi-ld:operationSpace", -    "orderBy": { -      "@container": "@list", -      "@id": "ngsi-ld:orderBy" -    }, -    "ordering": "ngsi-ld:ordering", -    "pick": "ngsi-ld:pick", -    "previousJson": { -      "@id": "ngsi-ld:hasPreviousJson", -      "@type": "@json" -    }, -    "previousLanguageMap": { -      "@id": "ngsi-ld:hasPreviousLanguageMap", -      "@container": "@language" -    }, -    "previousObject": { -      "@id": "ngsi-ld:hasPreviousObject", -      "@type": "@id" -    }, -    "previousObjectList": { -      "@id": "ngsi-ld:hasPreviousObjectList", -      "@container": "@list" -    }, -    "previousValue": "ngsi-ld:hasPreviousValue", -    "previousValueList": { -      "@id": "ngsi-ld:hasPreviousValueList", -      "@container": "@list" -    }, -    "previousVocab": { -      "@id": "ngsi-ld:hasPreviousVocab", -      "@type": "@vocab" -    }, -    "problemDetails": { -      "@id": "ngsi-ld:problemDetails", -      "@type": "@json" -    }, -    "properties": "geojson:properties", -    "propertyNames": { -      "@id": "ngsi-ld:propertyNames", -      "@type": "@vocab" -    }, -    "q": "ngsi-ld:q", -    "reason": "ngsi-ld:reason", -    "receiverInfo": "ngsi-ld:receiverInfo", -    "refreshRate": "ngsi-ld:refreshRate", -    "registrationId": "ngsi-ld:registrationId", -    "registrationName": "ngsi-ld:registrationName", -    "relationshipNames": { -      "@id": "ngsi-ld:relationshipNames", -      "@type": "@vocab" -}, -    "resultStatus": "ngsi-ld:resultStatus", -"scope": "ngsi-ld:scope", -"scopeQ": "ngsi-ld:scopeQ", -"showChanges": "ngsi-ld:showChanges", -    "snapshotId": "ngsi-ld:snapshotId", -    "snapshotLifetime": "ngsi-ld:snapshotLifetime", -    "snapshotPriority": "ngsi-ld:snapshotPriority", -    "snapshotQueries": { -      "@id": "ngsi-ld:snapshotQueries", -      "@container": "@list" -    }, -    "snapshotQueriesDetails": { -      "@id": "ngsi-ld:snapshotQueriesDetails", -      "@container": "@list" -    }, -    "snapshotStatus": "ngsi-ld:snapshotStatus", -    "snapshotTemporalQueries": { -      "@id": "ngsi-ld:snapshotTemporalQueries", -      "@container": "@list" -    }, -    "snapshotTemporalQueriesDetails": { -      "@id": "ngsi-ld:snapshotTemporalQueriesDetails", -      "@container": "@list" -    }, -    "startAt": { -      "@id": "ngsi-ld:startAt", -      "@type": "DateTime" -    }, -    "status": "ngsi-ld:status", -    "stddev": { -      "@id": "ngsi-ld:stddev", -      "@container": "@list" -    }, -    "subscriptionId": { -      "@id": "ngsi-ld:subscriptionId", -      "@type": "@id" -    }, -    "subscriptionName": "ngsi-ld:subscriptionName", -    "success": { -      "@id": "ngsi-ld:success", -      "@type": "@id" -    }, -    "sum": { -      "@id": "ngsi-ld:sum", -      "@container": "@list" -    }, -    "sumsq": { -      "@id": "ngsi-ld:sumsq", -      "@container": "@list" -    }, -    "sysAttrs": "ngsi-ld:sysAttrs", -    "temporalQ": "ngsi-ld:temporalQ", -    "tenant": { -      "@id": "ngsi-ld:tenant", -      "@type": "@id" -    }, -    "throttling": "ngsi-ld:throttling", -    "timeAt": { -      "@id": "ngsi-ld:timeAt", -      "@type": "DateTime" -    }, -    "timeInterval": "ngsi-ld:timeInterval", -    "timeout": "ngsi-ld:timeout", -    "timeproperty": "ngsi-ld:timeproperty", -    "timerel": "ngsi-ld:timerel", -    "timesFailed": "ngsi-ld:timesFailed", -    "timesSent": "ngsi-ld:timesSent", -    "title": "http://purl.org/dc/terms/title", -    "totalCount": { -      "@id": "ngsi-ld:totalCount", -      "@container": "@list" -    }, -    "triggerReason": "ngsi-ld:triggerReason", -    "typeList": { -      "@id": "ngsi-ld:typeList", -      "@type": "@vocab" -    }, -    "typeName": { -      "@id": "ngsi-ld:typeName", -      "@type": "@vocab" -    }, -    "typeNames": { -      "@id": "ngsi-ld:typeNames", -      "@type": "@vocab" -    }, -    "unchanged": "ngsi-ld:unchanged", -    "unitCode": "ngsi-ld:unitCode", -    "updated": "ngsi-ld:updated", -    "uri": "ngsi-ld:uri", -    "value": "ngsi-ld:hasValue", -    "valueList": { -      "@id": "ngsi-ld:hasValueList", -      "@container": "@list" -    }, -    "valueLists": { -      "@id": "ngsi-ld:hasValueLists", -      "@container": "@list" -    }, -    "values": { -      "@id": "ngsi-ld:hasValues", -      "@container": "@list" -    }, -    "valueType": { -      "@id": "ngsi-ld:hasValueType", -      "@type": "@vocab" -    }, -    "vocab": { -      "@id": "ngsi-ld:hasVocab", -      "@type": "@vocab" -    }, -    "vocabs": { -      "@id": "ngsi-ld:hasVocabs", -      "@container": "@list" -    }, -    "watchedAttributes": { -      "@id": "ngsi-ld:watchedAttributes", -      "@type": "@vocab" -    }, -    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" -  } -} -``` - -::: NO -NOTE: - -Implementers can take advantage of prefixed terms, i.e. in the form ngsi-ld:term, to provide a terser representation of the Core *\@context* . -::: diff --git a/API-md/15-annex-c-informative-examples-of-using-the-api.md b/API-md/15-annex-c-informative-examples-of-using-the-api.md deleted file mode 100644 index 594f4c5b04b0a39915c404c90105f30695dfa6ee..0000000000000000000000000000000000000000 --- a/API-md/15-annex-c-informative-examples-of-using-the-api.md +++ /dev/null @@ -1,3107 +0,0 @@ -# Annex C (informative): Examples of using the API {#annex-c-informative-examples-of-using-the-api number="15"} - -## C.1 Introduction {#c.1tabintroduction number="15.1"} - -This annex is informative and is intended to show in action the JSON-LD representation defined by NGSI-LD. - -JSON representations of the examples shown in this annex can be found at [[i.15]](7-tabreferences.md#i.15). - -## C.2 Entity Representation {#c.2tabentity-representation number="15.2"} - -### C.2.1 Property Graph {#c.2.1tabproperty-graph number="15.2.1"} - -[Figure C.2.1‑1](15-annex-c-informative-examples-of-using-the-api.md#Figure_C.2.1-1) shows a diagram representing a property graph to be used for the examples discussed in this clause. - -::: FL -![](./media/image143.png){style="width:6.56944in;height:5.56944in"} -::: - -::: {#Figure_C.2.1-1 .TF} -Figure C.2.1-1: Reference example -::: - -As per the algorithms described above and as per the rules for generating the JSON-LD representation of NGSI-LD entities the above graph will result in the following JSON-LD representations. The syntax has been checked using the JSON-LD Playground tool [[i.5]](7-tabreferences.md#i.5). - -### C.2.2 Vehicle Entity {#c.2.2tabvehicle-entity number="15.2.2"} - -**Normalized Representation** - -The normalized representation is a lossless representation of an Entity, where every *Property* is defined by a *type* and a *value* and every *Relationship* is defined by a *type* and an *object*. - -Below there is a representation of an Entity of Type ["Vehicle"]{.HTML_Code}. It can be observed that the *\@context* is composed of different parts, namely the Core *\@context* and several vocabulary-specific *\@contexts*. - -It is noteworthy that the *\@context* corresponding to the Parking domain is included as it is referenced through the *isParked* Relationship. - -**Normalized Representation when inline Linked Entity retrieval is used** - -When inline [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) is specified, any *Relationships* which target Entities stored locally or include an *objectType* Attribute are returned in an expanded format. Attributes of type["Relationship" ]{.HTML_Code}are returned with an additional *entity* sub-Attribute, which holds the normalized [Linked Entity]{.HTML_Keyboard} data corresponding to the *Relationship's* target *object* URI. Attributes of type["ListRelationship"]{.HTML_Code} are returned with an additional *entityList* sub-Attribute which in turn holds an ordered array of the normalized [Linked Entities]{.HTML_Keyboard} corresponding to the target "objectList" URIs. - -**Normalized Representation when flattened Linked Entity retrieval is used** - -When flattened [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)) is specified, an array of normalized Entities is returned. Whenever a *Relationship* Attribute targets an Entity stored locally or includes an *objectType*, an additional normalized [Linked Entity]{.HTML_Keyboard} holding data corresponding to the *Relationship's* target *object* URI is appended to the array. For Attributes of type ["ListRelationship]{.HTML_Code}["]{.HTML_Code}, an array of normalized [Linked Entities]{.HTML_Keyboard} is appended, which hold the data corresponding to each of the target URIs found within its *objectList*. - -[[]{.HTML_Sample} - -**Normalized Representation when Language Filter is used** - -When the Language Filter (see [clause 4.15](9-tabcontext-information-management-framework.md#tabngsi-ld-language-filter)) is used, Properties of type ["LanguageProperty"]{.HTML_Code} are returned as type ["Property",]{.HTML_Code} and their *languageMaps* are reduced to simple strings. For example if the language filter [lang=fr]{.HTML_Code} is specified, only the value for French language is present. - -``` json -{ -  "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -  "brandName": { -    "type": "Property", - "value": "Mercedes" - }, - "street": { - "type": "LanguageProperty", - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt - }  - }, -  "isParked": { -    "type": "Relationship", - "objectType": "OffStreetParking", -    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", -    "observedAt": "2017-07-29T12:00:04Z", -    "providedBy": { -         "type": "Relationship", -         "object": "urn:ngsi-ld:Person:Bob" -      }  -  }, -    "category": { -    "type": "VocabProperty", - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "type": "ListProperty", - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer", - "unitCode": "MMT" -}, -"passengers": { - "type": "Relationship", - "objectType": "Person", - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] - }, -"route": { - "type": "ListRelationship", - "objectType": "City", -   "objectList": [ -   {"object": "urn:ngsi-ld:City:Antwerp"}, - {"object": "urn:ngsi-ld:City:Rotterdam"} -   {"object": "urn:ngsi-ld:City:Amsterdam"} -   ] -    }, - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  - ] -} -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -    "type": "Vehicle", -  "brandName": { -    "type": "Property", - "value": "Mercedes" - }, - "street": { - "type": "LanguageProperty", - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt - }  - }, -    "isParked": { - "type": "Relationship", - "objectType": "OffStreetParking", - "object": "urn:ngsi-ld:OffStreetParking:Downtown1", -        "entity": { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": "OffStreetParking", - "name": { - "value": "Top Parking", - "type": "Property" - }, - "operatedBy": { - "object" "urn:ngsi-ld:Company:BigParkingCorp", - "type": "Relationship" - }, -  }, -        "observedAt": "2017-07-29T12:00:04Z", -        "providedBy": { -            "object": "urn:ngsi-ld:Person:Bob" -        }  -    }, - "category": { -    "type": "VocabProperty", - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "type": "ListProperty", - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer", - "unitCode": "MMT" -}, -"passengers": { - "type": "Relationship", - "objectType": "Person",  - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], - "entity": [ - { - "id": "urn:ngsi-ld:Person:Alice", - "type": "Person", - "name": { - "value": "Alice", - "type": "Property" - } - }, - { - "id": "urn:ngsi-ld:Person:Bob", - "type": "Person", - "name": { - "value": "Bob", - "type": "Property" - } - } - ] -}, -"route": { - "type": "ListRelationship", - "objectType": "City", - "objectList": [ -   {"object": "urn:ngsi-ld:City:Antwerp"}, - {"object": "urn:ngsi-ld:City:Rotterdam"} -   {"object": "urn:ngsi-ld:City:Amsterdam"} -   ], - "entityList": [ - { - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - "name": { - "value": "Antwerp", - "type": "Property" - } - }, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - "name": { - "value": "Rotterdam", - "type": "Property" - } - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - "name": { - "value": "Amsterdam", - "type": "Property" - } - } - ] -}, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -} - { -     "id": "urn:ngsi-ld:Vehicle:A4567", -     "type": "Vehicle", -     "brandName": { -    "type": "Property", - "value": "Mercedes" - }, - "street": { - "type": "LanguageProperty", - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt - }  - }, -  "isParked": { -    "type": "Relationship", - "objectType": "OffStreetParking", -    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", -    "observedAt": "2017-07-29T12:00:04Z", -    "providedBy": { -         "type": "Relationship", -         "object": "urn:ngsi-ld:Person:Bob" -      }  -  }, -     "category": { -    "type": "VocabProperty", - "vocab": "non-commercial" - }, - "tyreTreadDepths": { - "type": "ListProperty", - "valueList": [300, 300, 120,�[�6], -     "valueType": "Integer" - "unitCode": "MMT" - }, - "passengers": { -   "type": "Relationship", -   "objectType": "Person", -   "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] - }, - "route": { - "type": "ListRelationship", - "objectType": "City", - "objectList": [ -   {"object": "urn:ngsi-ld:City:Antwerp"}, - {"object": "urn:ngsi-ld:City:Rotterdam"} -   {"object": "urn:ngsi-ld:City:Amsterdam"} -   ] - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": "OffStreetParking", - "name": { - "value": "Top Parking", - "type": "Property" - }, - "operatedBy": { - "object": "urn:ngsi-ld:Company:BigParkingCorp", - "type": "Relationship" - }, -        "observedAt": "2017-07-29T12:00:04Z", -        "providedBy": { -            "object": "urn:ngsi-ld:Person:Bob" -        }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:Person:Alice", - "type": "Person", - "name": { - "value": "Alice", - "type": "Property" - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:Person:Bob", - "type": "Person", - "name": { - "value": "Bob", - "type": "Property" - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, -{ - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - "name": { - "value": "Antwerp", - "type": "Property" - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - "name": { - "value": "Rotterdam", - "type": "Property" - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - "name": { - "value": "Amsterdam", - "type": "Property" - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] - } -] -{ -  "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -  "brandName": { -    "type": "Property", - "value": "Mercedes" - }, - "street": { - "type": "Property", - "value": "Grand Place", - "lang": "fr" - }, -  "isParked": { -    "type": "Relationship", -    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", -    "observedAt": "2017-07-29T12:00:04Z", -    "providedBy": { -         "type": "Relationship", -         "object": "urn:ngsi-ld:Person:Bob" -      }  -  }, -    "category": { -    "type": "VocabProperty", - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "type": "ListProperty", - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer", - "unitCode": "MMT" -}, -"passengers": { - "type": "Relationship", -    "objectType": "Person", - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] -}, -"route": { - "type": "ListRelationship", - "objectType": "City", - "objectList": [ -   {"object": "urn:ngsi-ld:City:Antwerp"}, - {"object": "urn:ngsi-ld:City:Rotterdam"} -   {"object": "urn:ngsi-ld:City:Amsterdam"} -   ] -}, -"@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  - ] -} -``` - -**Concise Representation** - -The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute *type* members are omitted and the following rules are applied: - -::: B1plus -- Every *Property* without further sub-attributes is represented directly by the *Property* value only. -- Every *Property* that includes further sub-attributes is represented by a value key-value pair. -- Every *GeoProperty* without further sub-attributes is represented by the *GeoProperty's* GeoJSON representation only. -- Every *GeoProperty* that includes further sub-attributes is represented by a value key-value pair. -- Every *LanguageProperty* is represented by a *languageMap* key-value pair. -- Every *ListProperty* is represented directly by the array of *Property* values. -- Every *JsonProperty* is represented by a *json* the value of which is raw JSON which is not available for JSON-LD representation. -- Every *VocabProperty* is represented by a *vocab* the value of which is a compacted URI. -- Every *Relationship* is represented by an object key-value pair. -- Every *ListRelationship* is represented by an array of URIs. -::: - -**Concise Representation when inline Linked Entity retrieval is used** - -When inline [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) is specified, any *Relationships* which target Entities stored locally or include an *objectType* Attribute are returned in an expanded format. The concise [Linked Entity]{.HTML_Keyboard} data corresponding to the *Relationship's* target *object* URI is returned within an *entity* sub-Attribute. Attributes of type ["ListRelationship]{.HTML_Code}["]{.HTML_Code}are returned within an *entityList* sub-Attribute which in turn holds an ordered array of the [Linked Entities]{.HTML_Keyboard} in the concise format corresponding to each of the target*objectList* URIs. - -[ "name": " Antwerp"]{.HTML_Sample} - -[ "name": "Rotterdam]{.HTML_Sample} - -[ "name": "Amsterdam"]{.HTML_Sample} - -**Concise Representation when flattened Linked Entity retrieval is used** - -When flattened [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)) is specified, an array of concise Entities is returned. Whenever a *Relationship* Attribute targets an Entity stored locally or includes an *objectType*, an additional concise [Linked Entity]{.HTML_Keyboard} holding data corresponding to the *Relationship's* target *object* URI is appended to the response. For Attributes of type ["ListRelationship]{.HTML_Code}["]{.HTML_Code}, an array of concise [Linked Entities]{.HTML_Keyboard} is appended to the response which hold the data corresponding to each of the target URIs found within its *objectList*. - -[[]{.HTML_Sample} - -**Concise representation when Language Filter is used** - -The rules apply as defined in the previous examples. For example if the language filter [lang=fr]{.HTML_Code} is specified. - -**Simplified Representation** - -The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only. - -**Simplified Representation when inline Linked Entity retrieval is used** - -When inline [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) is specified, any *Relationships* which target Entities stored locally or include an *objectType* Attribute are returned as a JSON object holding key-value pairs corresponding to the data from the *Relationship's* target *object* URI in simplified format. Attributes of type ["ListRelationship]{.HTML_Code}["]{.HTML_Code}are returned as array of JSON objects each holding key-value pairs corresponding to the data obtained from the target *objectList* URIs. - -**Simplified Representation when flattened** [Linked Entity]{.HTML_Keyboard} **retrieval is used** - -When flattened [Linked Entity]{.HTML_Keyboard} retrieval (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)) is specified, an array of JSON Objects is returned. Whenever a *Relationship* Attribute targets an Entity stored locally or includes an *objectType*, an additional JSON Object of key-value pairs holding data corresponding to the *Relationship's* target *object* URI is appended to the response. For Attributes of type ["ListRelationship]{.HTML_Code}["]{.HTML_Code}, an array of JSON Objects each holding key-value pairs corresponding to the data obtained from the target *objectList* URIs is appended to the response. - -[[]{.HTML_Sample} - -**Simplified Representation of Natural Language Attributes** - -The simplified natural language representation is a collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph, and where *languageMaps* are reduced to simple string properties. For example if the language filter [lang=fr]{.HTML_Code} is specified. - -**Multiple attribute example** - -Below is an example, where the speed of the car is provided by two different sources. As both may be relevant at the same time, there are two individual attribute instances for speed; each is identified by a *datasetId* and both instances are represented in an array. The *datasetId* enables individually creating, updating and deleting a particular instance without affecting the instance from another source. - -**Simplified Representation of a multi-attribute** - -The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only. - -### C.2.3 Parking Entity {#c.2.3tabparking-entity number="15.2.3"} - -**Normalized Representation** - -The normalized representation is a lossless representation of an Entity, where every *Property* is defined by a *type* and a *value* and every *Relationship* is defined by a *type* and an *object*. - -Below there is a representation of an Entity of Type ["OffStreetParking"]{.HTML_Code}. It can be observed that the *\@context* is composed of two different elements, the Core one and the vocabulary-specific one. - -``` json -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -    "type": "Vehicle", -    "brandName": "Mercedes", -    "street": { -        "languageMap": { -            "fr": "Grand Place", -            "nl": "Grote Markt" -        }  -    }, -    "isParked": { -        "object": "urn:ngsi-ld:OffStreetParking:Downtown1", - "objectType": "OffStreetParking", -        "observedAt": "2017-07-29T12:00:04Z", -        "providedBy": { -            "object": "urn:ngsi-ld:Person:Bob" -        }  -    }, - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer" - "unitCode": "MMT" -}, -"passengers": { - "objectType": "Person", - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] -}, -"route": { - "objectType": "City", - "objectList": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" - ] - }, -"@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -} -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -    "type": "Vehicle", -    "brandName": "Mercedes", -    "street": { -        "languageMap": { -            "fr": "Grand Place", -            "nl": "Grote Markt" -        }  -    }, -    "isParked": { - "object": "urn:ngsi-ld:OffStreetParking:Downtown1", - "objectType": "OffStreetParking", -        "entity": { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": "OffStreetParking", - "name": "Top Parking", - "operatedBy": { - "object": "urn:ngsi-ld:Company:BigParkingCorp" -     } -  }, -        "observedAt": "2017-07-29T12:00:04Z", -        "providedBy": { -            "object": "urn:ngsi-ld:Person:Bob" -        }  -    }, - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer", - "unitCode": "MMT" -}, -"passengers": { - "objectType": "Person", - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], - "entity": [ -   { - "id": "urn:ngsi-ld:Person:Alice", - "type": "Person", - "name": "Alice" -    }, -    { - "id": "urn:ngsi-ld:Person:Bob", - "type": "Person", - "name": "Bob" -    } -] -}, -"route": { - "objectType": "City", - "objectList": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" - ], - "entityList": [ - { - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - }, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - } - ] -}, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -} - { -     "id": "urn:ngsi-ld:Vehicle:A4567", -     "type": "Vehicle", -     "brandName": "Mercedes", -     "street": { -         "languageMap": { -             "fr": "Grand Place", -             "nl": "Grote Markt" -         }  -     }, -        "isParked": {  - "object": "urn:ngsi-ld:OffStreetParking:Downtown1", - "objectType": "OffStreetParking", -         "observedAt": "2017-07-29T12:00:04Z", -         "providedBy": { -             "object": "urn:ngsi-ld:Person:Bob" -         }  -     }, - "category": { - "vocab": "non-commercial" - }, - "tyreTreadDepths": { - "valueList": [300, 300, 120,�[�6], -     "valueType": "Integer", - "unitCode": "MMT" - }, - "passengers": { - "objectType": "Person", - "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] - }, - "route": { - "objectType": "City", - "objectList": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" -   ] - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": "OffStreetParking", - "name": "Top Parking", - "operatedBy": { - "object" "urn:ngsi-ld:Company:BigParkingCorp", - }, -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": " urn:ngsi-ld:Person:Alice", - "type": "Person", - "name": "Alice", -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": " urn:ngsi-ld:Person:Bob", - "type": "Person", - "name": "Bob", -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, -{ - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - "name": " Antwerp", -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] -}, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - "name": "Rotterdam", -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - "name": "Amsterdam", -    "@context": [ -        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", -        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"  -    ] - } -] -{ -  "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -  "brandName": "Mercedes" - }, - "street": { - "value": "Grand Place", - "lang": "fr" - }, -  "isParked": { - "objectType": "OffStreetParking", -    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", -    "observedAt": "2017-07-29T12:00:04Z", -    "providedBy": { -         "object": "urn:ngsi-ld:Person:Bob" -      }  -  }, - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": { - "valueList": [300, 300, 120,�[�6], -    "valueType": "Integer", - "unitCode": "MMT" -}, -"passengers": { - "objectType": "Person", -   "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] -}, -"route": { - "objectType": "City", - "objectList": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" -   ] -}, - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -   "brandName": "Mercedes", - "street": { - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt"  - } - } -   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": [300, 300, 120,�[�6], -"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], -"route": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" -], - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -   "brandName": "Mercedes", - "street": { - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt"  - } - }, -   "isParked": { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": " OffStreetParking",   - "name": "Top Parking", - "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" - }, - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": [300, 300, 120,�[�6], -"passengers": [ - { - "id": "urn:ngsi-ld:Person:Alice", - "type": "Person",  - "name": "Alice" - }, - { - "id": "urn:ngsi-ld:Person:Bob", - "type": "Person",  - "name": "Bob" - } -], -    "route": [ -   { - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - "name": " Antwerp" -     }, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - "name": "Rotterdam - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - "name": "Amsterdam" -     } -    ], - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -   "brandName": "Mercedes", - "street": { - "languageMap": { - "fr": "Grand Place", - "nl": "Grote Markt"  - } - } -   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": [300, 300, 120,�[�6], -"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], - "route": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" - ], - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -}, -{ - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": " OffStreetParking",   - "name": "Top Parking", - "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" -}, -{ - "id": "urn:ngsi-ld:Person:Alice", - "type": "Person",  - "name": "Alice" -} -{ - "id": "urn:ngsi-ld:Person:Bob", - "type": "Person",  - "name": "Bob" -}, -{ - "id": "urn:ngsi-ld:City:Antwerp", - "type": "City", - "name": " Antwerp" -}, - { - "id": "urn:ngsi-ld:City:Rotterdam", - "type": "City", - "name": "Rotterdam - }, - { - "id": "urn:ngsi-ld:City:Amsterdam", - "type": "City", - "name": "Amsterdam" -} -] -{ -    "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -   "brandName": "Mercedes", - "street": "Grand Place", -   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", - "category": { - "vocab": "non-commercial" - }, -"tyreTreadDepths": [300, 300, 120,�[�6], -"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], -"route": [ -   "urn:ngsi-ld:City:Antwerp", - "urn:ngsi-ld:City:Rotterdam", -   "urn:ngsi-ld:City:Amsterdam" -], - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -{ -  "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -  "speed": [{ -    "type": "Property", - "value": 55, - "source": { -     "type": "Property", - "value": "Speedometer" - }, - "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" - }, - { -    "type": "Property", - "value": 54.5, - "source": { -     "type": "Property", - "value": "GPS" - }, - "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" - }], - "@context": [ -      { - "Vehicle": "http://example.org/Vehicle", - "speed": "http://example.org/speed", -      "source": "http://example.org/hasSource" -     }, -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -   ] -} -{ -  "id": "urn:ngsi-ld:Vehicle:A4567", -   "type": "Vehicle", -  "speed": { - "dataset": { - "urn:ngsi-ld:Property:speedometerA4567-speed": 55, - "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5 - } - }, - "@context": [ -      { - "Vehicle": "http://example.org/Vehicle", - "speed": "http://example.org/speed" -     }, -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -   ] -} -{ -   "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -   "type": "OffStreetParking", - "name": { - "type": "Property", -     "value": "Downtown One" - }, -   "availableSpotNumber": { -     "type": "Property", -     "value": 121, - "observedAt": "2017-07-29T12:05:02Z", -     "reliability": { -       "type": "Property", -       "value": 0.7 -     }, -     "providedBy": { -        "type": "Relationship", -        "object": "urn:ngsi-ld:Camera:C1" -     } - }, - "totalSpotNumber": { -     "type": "Property", -     "value": 200 - }, - "location": { - "type": "GeoProperty", - "value": { - "type": "Point", - "coordinates": [-8.5, 41.2] - } - }, - "@context": [ - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -``` - -**Concise Representation** - -The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute *type* members are omitted and the following rules are applied: - -::: B1plus -- Every *Property* without further sub-attributes is represented by the *Property* value only. -- Every *Property* that includes further sub-attributes is represented by a value key-value pair. -- Every *GeoProperty* without further sub-attributes is represented by the *GeoProperty's* GeoJSON representation only. -- Every *GeoProperty* that includes further sub-attributes is represented by a value key-value pair. -- Every *LanguageProperty* is defined by a *languageMap* key-value pair. -- Every *VocabProperty* is represented by a *vocab* the value of which is a compacted URI. -- Every *Relationship* is defined by an object key-value pair. -::: - -**Simplified representation** - -The Simplified Representation (also known as ["]{.HTML_Code}[keyValues]{.HTML_Code}["]{.HTML_Code}) is a lossy, collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only. - -**Normalized GeoJSON Representation** - -The normalized GeoJSON representation of a single Entity is defined as a single GeoJSON *Feature* object as follows: - -The GeoJSON representation of multiple Entities is defined as a GeoJSON *FeatureCollection* object containing an array of GeoJSON features corresponding to the individual Entity representations. - -**Concise GeoJSON Representation** - -The concise GeoJSON representation of a single Entity is defined as a single GeoJSON *Feature* object as follows: - -The concise GeoJSON representation of multiple Entities is defined as a GeoJSON *FeatureCollection* object containing an array of GeoJSON features corresponding to the individual Entity representations in concise GeoJSON format. - -**Simplified GeoJSON Representation** - -The simplified GeoJSON representation of a single Entity is defined as a single GeoJSON *Feature* object where the properties represent a collapsed representation of the Entity, which focuses on Property Values and Relationship objects present at the first level of the graph. - -The simplified GeoJSON representation of multiple Entities is defined as a GeoJSON *FeatureCollection* object containing an array of GeoJSON features corresponding to the individual Entity representations in simplified GeoJSON format. - -``` json -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "OffStreetParking", -  "name": "Downtown One", -  "availableSpotNumber": { -    "value": 121, -    "observedAt": "2017-07-29T12:05:02Z", -    "reliability": 0.7, -    "providedBy": { -      "object": "urn:ngsi-ld:Camera:C1" -    } -  }, -  "totalSpotNumber": 200, -  "location": { -    "type": "Point", -    "coordinates": [ -      -8.5, -      41.2 -    ] -  }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -    "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -    "type": "OffStreetParking", - "name": "Downtown One", -    "availableSpotNumber": 121, - "totalSpotNumber": 200, - "location": { - "type": "Point", - "coordinates": [-8.5, 41.2] - }, - "@context": [ -     "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "Feature", -  "geometry": { -    "type": "Point", -    "coordinates": [-8.51, 41.1] -  }, -  "properties": { -    "type": "OffStreetParking", -    "name": { -      "type": "Property", -      "value": "Downtown One" -    }, -    "availableSpotNumber": { -      "type": "Property", -      "value": 121, -      "observedAt": "2017-07-29T12:05:02Z", -      "reliability": { -        "type": "Property", -        "value": 0.7 -      }, -      "providedBy": { -        "type": "Relationship", -        "object": "urn:ngsi-ld:Camera:C1" -      } -    }, - "location": { - "type": "GeoProperty", - "value": { - "type": "Point", - "coordinates": [-8.51, 41.1] - } - }, -    "totalSpotNumber": { -      "type": "Property", -      "value": 200 -    }, -    "@context": [ -      "http://example.org/ngsi-ld/latest/parking.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -} -{ -  "type": "FeatureCollection", -  "features": [ -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [-8.5, 41.1] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": { -          "type": "Property", -          "value": "Downtown One" -        }, -        "availableSpotNumber": { -          "type": "Property", -          "value": 121, -          "observedAt": "2017-07-29T12:05:02Z", -          "reliability": { -            "type": "Property", -            "value": 0.7 -          }, -          "providedBy": { -            "type": "Relationship", -            "object": "urn:ngsi-ld:Camera:C1" -          } -        }, -        "totalSpotNumber": { -          "type": "Property", -          "value": 200 -        }, - "location": { -   "type": "GeoProperty", -   "value": { - "type": "Point", - "coordinates": [-8.51, 41.1] -   } - } -      } -    }, -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [-8.51, 41.1] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": { -          "type": "Property", -          "value": "Downtown Two" -        }, -        "availableSpotNumber": { -          "type": "Property", -          "value": 99, -          "observedAt": "2017-07-29T12:05:02Z", -          "reliability": { -            "type": "Property", -            "value": 0.8 -          }, -          "providedBy": { -            "type": "Relationship", -            "object": "urn:ngsi-ld:Camera:C2" -          } -        }, -        "totalSpotNumber": { -          "type": "Property", -          "value": 100 -        }, - "location": { -   "type": "GeoProperty", -   "value": { - "type": "Point", - "coordinates": [-8.51, 41.1] -   } - } -      } -    } -  ], -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "Feature", -  "geometry": { -    "type": "Point", -    "coordinates": [ -      -8.51, -      41.1 -    ] -  }, -  "properties": { -    "type": "OffStreetParking", -    "name": "Downtown One", -    "availableSpotNumber": { -      "value": 121, -      "observedAt": "2017-07-29T12:05:02Z", -      "reliability": 0.7, -      "providedBy": { -        "object": "urn:ngsi-ld:Camera:C1" -      } -    }, -    "location": { -      "type": "Point", -      "coordinates": [ -        -8.51, -        41.1 -      ] -    }, -    "totalSpotNumber": 200, -    "@context": [ -      "http://example.org/ngsi-ld/latest/parking.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -} -{ -  "type": "FeatureCollection", -  "features": [ -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [ -          -8.5, -          41.1 -        ] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": "Downtown One", -        "availableSpotNumber": { -          "value": 121, -          "observedAt": "2017-07-29T12:05:02Z", -          "reliability": 0.7, -          "providedBy": { -            "object": "urn:ngsi-ld:Camera:C1" -          } -        }, -        "totalSpotNumber": 200, -        "location": { -          "type": "Point", -          "coordinates": [ -            -8.51, -            41.1 -          ] -        } -      } -    }, -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [ -          -8.51, -          41.1 -        ] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": "Downtown Two", -        "availableSpotNumber": { -          "value": 99, -          "observedAt": "2017-07-29T12:05:02Z", -          "reliability": 0.8, -          "providedBy": { -            "object": "urn:ngsi-ld:Camera:C2" -          } -        }, -        "totalSpotNumber": 100, -        "location": { -          "type": "Point", -          "coordinates": [ -            -8.51, -            41.1 -          ] -        } -      } -    } -  ], -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -  "id": "urn:ngsi-ld:offstreetparking:Downtown1", -  "type": "Feature", -  "geometry": { -    "type": "Point", -    "coordinates": [-8.51, 41.1] -  }, -  "properties": { -    "type": "OffStreetParking", -    "name": "Downtown One", -    "availableSpotNumber": 121, -    "totalSpotNumber": 200, -    "location": { -   "type": "Point", -   "coordinates": [-8.51, 41.1] - } -  }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -  "type": "FeatureCollection", -  "features": [ -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [-8.5, 41.2] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": "Downtown One", -        "availableSpotNumber": 121, -        "totalSpotNumber": 200, -        "location": { -    "type": "Point", -    "coordinates": [-8.5, 41.2] -     } -      } -    }, -    { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", -      "type": "Feature", -      "geometry": { -        "type": "Point", -        "coordinates": [-8.51, 41.1] -      }, -      "properties": { -        "type": "OffStreetParking", -        "name": "Downtown Two", -        "availableSpotNumber": 99, -        "totalSpotNumber": 100, -        "location": { -    "type": "Point", -    "coordinates": [-8.51, 41.1] -     } -      } -    } -  ], -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -}   -``` - -### C.2.4 \@context {#c.2.4tabcontext number="15.2.4"} - -The disposition of the *\@context* can be as an inline JSON object, as a dereferenceable URI or as a (multiple) combination of both. In the examples above the *\@context* is provided through several dereferenceable URIs. The resulting *\@context* (obtained by merging the content of the resource referenced by the referred URIs) is shown below. - -::: NO -NOTE 1: - -For brevity reasons the *\@context* does not contain the API terms defined by [clause 5.2](10-tabapi-operation-definition.md#tabdata-types) . -::: - -::: NO -NOTE 2: - -Some extra terms are defined because they will be used in examples later presented. -::: - -## C.3 Context Source Registration {#c.3tabcontext-source-registration number="15.3"} - -Below there is an example representation of a [Context Source Registration]{.HTML_Keyboard}. It makes use of the *\@context* formerly described. - -The Registration is referring to a Temporal [Context Source]{.HTML_Keyboard} capable of providing temporal information from Entities of type ["]{.HTML_Code}[Vehicle]{.HTML_Code}["]{.HTML_Code} and ["]{.HTML_Code}[OffStreetParking]{.HTML_Code}["]{.HTML_Code}, meeting certain id requirements. More concretely, it can only provide the referenced Properties and Relationships. Temporal information is provided for the given *managementInterval*, i.e. related to *createdAt* and *modifiedAt* Temporal Properties. The *managementInterval* is specified as an open interval, so only a starting point is given. In addition, the Registration example covers a particular geographical area. - -## C.4 Context Subscription {#c.4tabcontext-subscription number="15.4"} - -Below there is an example of a Context Subscription. It makes use of the *\@context* formerly described. - -``` json -{ - "id": "@id", - "type": "@type", - "Property": "https://uri.etsi.org/ngsi-ld/Property", - "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship", - "value": "https://uri.etsi.org/ngsi-ld/hasValue", - "object": { - "@type": "@id", - "@id": "https://uri.etsi.org/ngsi-ld/hasObject" - }, - "observedAt": { - "@type": "https://uri.etsi.org/ngsi-ld/DateTime", - "@id": "https://uri.etsi.org/ngsi-ld/observedAt" -}, - "datasetId": { - "@id": "https://uri.etsi.org/ngsi-ld/datasetId", - "@type":"@id" - }, - "location": "https://uri.etsi.org/ngsi-ld/location", -"GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty", - "Vehicle": "http://example.org/vehicle/Vehicle", - "street": "http://example.org/vehicle/street", - "brandName": "http://example.org/vehicle/brandName", - "category": "http://example.org/vehicle/category", - "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths", - "passengers": "http://example.org/vehicle/passengers", - "speed": "http://example.org/vehicle/speed", - "isParked": { - "@type": "@id", - "@id": "http://example.org/common/isParked" - }, - "OffStreetParking": "http://example.org/parking/OffStreetParking", - "availableSpotNumber": "http://example.org/parking/availableSpotNumber", - "totalSpotNumber": "http://example.org/parking/totalSpotNumber", - "isNextToBuilding": { - "@type": "@id", - "@id": "http://example.org/common/isNextToBuilding" - }, - "reliability": "http://example.org/common/reliability",  - "providedBy": { - "@type": "@id", - "@id": "http://example.org/common/providedBy" - }, - "name": "http://example.org/common/name", -"commercial": -"http://example.org/vehicle/commercial", - "non-commercial": "http://example.org/vehicle/non-commercial", -"Integer": "http://www.w3.org/2001/XMLSchema#Integer -} -{ - "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456", -    "type": "ContextSourceRegistration", -    "information": [ -   { - "entities": [  - { -             "id": "urn:ngsi-ld:Vehicle:A456", - "type": "Vehicle" -            } - ], - "propertyNames": ["brandName","speed"], -  "relationshipNames": ["isParked"] -   },  -   { - "entities": [ - { -             "idPattern": ".*downtown$", - "type": "OffStreetParking" -            }, - { -                "idPattern": ".*47$", - "type": "OffStreetParking" -            } - ], - "propertyNames": ["availableSpotNumber","totalSpotNumber"], - "relationshipNames": ["isNextToBuilding"] -      } - ], - "endpoint": "http://my.csource.org:1026", - "location": { - "type": "Polygon", - "coordinates": [ -             [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], -               [100.0, 1.0], [100.0, 0.0]] ] -    }, -    "managementInterval": { - "startAt": " 2017-11-29T14:53:15Z" -    }, - "@context": [ - "http://example.org/ngsi-ld/latest/commonTerms.jsonld", - "http://example.org/ngsi-ld/latest/vehicle.jsonld",  - "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -} -{ - "id": "urn:ngsi-ld:Subscription:mySubscription", -    "type": "Subscription", -    "entities": [ - { - "type": "Vehicle" -    } - ], -    "watchedAttributes": ["speed"], -    "q": "speed>50", -    "geoQ": { - "georel": "near;maxDistance==2000", -        "geometry": "Point", -        "coordinates": [-1,100] -    }, -    "notification": { -        "attributes": ["speed"], -        "format": "keyValues", -        "endpoint": { -           "uri": "http://my.endpoint.org/notify", -           "accept": "application/json" -        } -    }, - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] -} -``` - -The subject of the Context Subscription is Entities of Type *Vehicle* which *speed* is greater than 50, and located close to a certain area defined by a reference spatial point. Every time the *speed* (watched Attribute) of a concerned vehicle, changes, a new notification (including the new speed value) will be received in the specified endpoint. - -## C.5 HTTP REST API Examples {#c.5tabhttp-rest-api-examples number="15.5"} - -### C.5.1 Introduction {#c.5.1tabintroduction number="15.5.1"} - -This clause introduces some simple usage examples of the NGSI-LD API (HTTP REST binding). They are not intended to be exhaustive but just a sample for helping readers to understand better the present document. ETSI ISG CIM published a Developer's Primer with many more examples, see ETSI GR CIM 008 [[i.21]](7-tabreferences.md#i.21). - -### C.5.2 Create Entity of Type Vehicle {#c.5.2tabcreate-entity-of-type-vehicle number="15.5.2"} - -#### C.5.2.1 HTTP Request {#c.5.2.1tabhttp-request number="15.5.2.1"} - -::: B1 -**POST** /ngsi-ld/v1/entities/ -::: - -::: B1 -Content-Type: application/ld+json -::: - -::: B1 -Content-Length: 556 -::: - -::: B1 - -::: - -#### C.5.2.2 HTTP Response {#c.5.2.2tabhttp-response number="15.5.2.2"} - -::: B1 -201 Created -::: - -::: B1 -Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 -::: - -### C.5.3 Query Entities {#c.5.3tabquery-entities number="15.5.3"} - -#### C.5.3.1 Introduction {#c.5.3.1tabintroduction number="15.5.3.1"} - -::: EX -EXAMPLE: - -Give back all the Entities of type ["Vehicle"]{.HTML_Code} whose *brandName* attribute is not ["Mercedes"]{.HTML_Code} . Only give back the *brandName* attribute and provide the data in the NGSI-LD Simplified Format. -::: - -#### C.5.3.2 HTTP Request {#c.5.3.2tabhttp-request number="15.5.3.2"} - -::: B1 -**GET** /ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified** -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.3.3 HTTP Response {#c.5.3.3tabhttp-response number="15.5.3.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "brandName": "Volvo", -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.4 Query Entities (Pagination) {#c.5.4tabquery-entities-pagination number="15.5.4"} - -#### C.5.4.1 Introduction {#c.5.4.1tabintroduction number="15.5.4.1"} - -::: EX -EXAMPLE: - -Give back all the Entities of type ["Vehicle"]{.HTML_Code} . Only give back the *brandName* attribute and provide the data in the NGSI-LD Simplified Format. Limit the number of entities retrieved to 2. -::: - -#### C.5.4.2 HTTP Request {#c.5.4.2tabhttp-request number="15.5.4.2"} - -::: B1 -**GET** /ngsi-ld/v1/entities/?type= Vehicle&format=**simplified**&limit=2 -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.4.3 HTTP Response {#c.5.4.3tabhttp-response number="15.5.4.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -::: B1 -Link: ; rel="next"; type="application/ld+json" -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "brandName": "Volvo", -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  }, -  { -    "id": "urn:ngsi-ld:Vehicle:A456", -    "type": "Vehicle", -    "brandName": "Mercedes", -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.5 Temporal Query {#c.5.5tabtemporal-query number="15.5.5"} - -#### C.5.5.1 Introduction {#c.5.5.1tabintroduction number="15.5.5.1"} - -::: EX -EXAMPLE 1: - -Give back the temporal evolution of the attribute *speed* of Entities of type ["Vehicle"]{.HTML_Code} whose *brandName* attribute is not ["Mercedes"]{.HTML_Code} between the 1 ^st^ of August at noon and the 1 ^st^ of August at 01 PM. -::: - -::: EX -EXAMPLE 2: - -Give back the temporal evolution of the attribute *speed* and *brandName* of Entities of type ["Vehicle"]{.HTML_Code} whose *brandName* attribute is not ["Mercedes"]{.HTML_Code} between the 1 ^st^ of August at noon and the 1 ^st^ of August at 01 PM. As *brandName* attribute does not have any temporal evolution, *brandName* attribute is omitted in the response. -::: - -#### C.5.5.2 HTTP Request #1 {#c.5.5.2tabhttp-request-1 number="15.5.5.2"} - -::: B1 -**GET** /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.5.3 HTTP Response #1 {#c.5.5.3tabhttp-response-1 number="15.5.5.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "speed": [ -      { -        "type": "Property", -        "value": 120, -        "observedAt": "2018-08-01T12:03:00Z" -      }, -      { -        "type": "Property", -        "value": 80, -        "observedAt": "2018-08-01T12:05:00Z" -      }, -      { -        "type": "Property", -        "value": 100, -        "observedAt": "2018-08-01T12:07:00Z" -      } -    ], -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -]  -``` - -#### C.5.5.4 HTTP Request #2 {#c.5.5.4tabhttp-request-2 number="15.5.5.4"} - -::: B1 -**GET** /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.5.5 HTTP Response #2 {#c.5.5.5tabhttp-response-2 number="15.5.5.5"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "speed": [ -      { -        "type": "Property", -        "value": 120, -        "observedAt": "2018-08-01T12:03:00Z" -      }, -      { -        "type": "Property", -        "value": 80, -        "observedAt": "2018-08-01T12:05:00Z" -      }, -      { -        "type": "Property", -        "value": 100, -        "observedAt": "2018-08-01T12:07:00Z" -      } -    ], -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.6 Temporal Query (Simplified Representation) {#c.5.6tabtemporal-query-simplified-representation number="15.5.6"} - -#### C.5.6.1 Introduction {#c.5.6.1tabintroduction number="15.5.6.1"} - -::: EX -EXAMPLE: - -Give back the temporal evolution of the *speed* attribute for Entities of type ["Vehicle"]{.HTML_Code} whose *brandName* attribute is not ["Mercedes"]{.HTML_Code} between the 1 ^st^ of August at noon and the 1 ^st^ of August at 01 PM. Simplified representation is required. -::: - -#### C.5.6.2 HTTP Request {#c.5.6.2tabhttp-request number="15.5.6.2"} - -::: B1 -**GET** /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=**temporalValues** -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.6.3 HTTP Response {#c.5.6.3tabhttp-response number="15.5.6.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "speed": { -      "type": "Property", -      "values": [ -        [ -          120, -          "2018-08-01T12:03:00Z" -        ], -        [ -          80, -          "2018-08-01T12:05:00Z" -        ], -        [ -          100, -          "2018-08-01T12:07:00Z" -        ] -      ] -    }, -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.7 Retrieve Available Entity Types {#c.5.7tabretrieve-available-entity-types number="15.5.7"} - -#### C.5.7.1 Introduction {#c.5.7.1tabintroduction number="15.5.7.1"} - -::: EX -EXAMPLE: - -Give back all entity types for which entity instances are currently available in the NGSI-LD system. -::: - -#### C.5.7.2 HTTP Request {#c.5.7.2tabhttp-request number="15.5.7.2"} - -::: B1 -**GET** /ngsi-ld/v1/types -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.7.3 HTTP Response {#c.5.7.3tabhttp-response number="15.5.7.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -  "id": "urn:ngsi-ld:EntityTypeList:34534657", -  "type": "EntityTypeList", -  "typeList": [ -    "Vehicle", -    "OffStreetParking", -    "http://example.org/parking/ParkingSpot" -  ] -} -``` - -::: NO -NOTE: - -All entity types that can be found in the provided *\@context* are given as short names, the others as Fully Qualified Names (FQNs). -::: - -### C.5.8 Retrieve Details of Available Entity Types {#c.5.8tabretrieve-details-of-available-entity-types number="15.5.8"} - -#### C.5.8.1 Introduction {#c.5.8.1tabintroduction number="15.5.8.1"} - -::: EX -EXAMPLE: - -Give back the details of all entity types for which entity instances are currently available in the NGSI-LD system. -::: - -#### C.5.8.2 HTTP Request {#c.5.8.2tabhttp-request number="15.5.8.2"} - -::: B1 -**GET** /ngsi-ld/v1/types?details=true -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.8.3 HTTP Response {#c.5.8.3tabhttp-response number="15.5.8.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -[ -  { -    "id": "http://example.org/vehicle/Vehicle", -    "type": "EntityType", -    "typeName": "Vehicle", -    "attributeNames": [ -      "brandName", -      "isParked", -      "location", -      "speed" -    ] -  }, -  { -    "id": "http://example.org/parking/OffStreetParking", -    "type": "EntityType", -    "typeName": "OffStreetParking", -    "attributeNames": [ -      "availableSpotNumber", -      "isNextToBuilding", -      "location", -      "totalSpotNumber" -    ] -  }, -  { -    "id": "http://example.org/parking/ParkingSpot", -    "type": "EntityType", -    "typeName": "http://example.org/parking/ParkingSpot", -    "attributeNames":[ -      "location", -      "http://example.org/parking/status" -    ] -  } -]  -``` - -::: NO -NOTE: - -The type name of all entity types and all attribute names that can be found in the provided *\@context* are given as short names, the others as Fully Qualified Names (FQNs). The id is always an FQN. -::: - -### C.5.9 Retrieve Available Entity Type Information {#c.5.9tabretrieve-available-entity-type-information number="15.5.9"} - -#### C.5.9.1 Introduction {#c.5.9.1tabintroduction number="15.5.9.1"} - -::: EX -EXAMPLE: - -Give back the details of entity type ["Vehicle"]{.HTML_Code} (for which entity instances are currently available in the NGSI-LD system). -::: - -#### C.5.9.2 HTTP Request {#c.5.9.2tabhttp-request number="15.5.9.2"} - -::: B1 -**GET** /ngsi-ld/v1/types/Vehicle -::: - -::: B1 -[Alternative with FQN: **GET** /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle] -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.9.3 HTTP Response {#c.5.9.3tabhttp-response number="15.5.9.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -  "id": "http://example.org/vehicle/Vehicle", -  "type": "EntityTypeInfo", -  "typeName": "Vehicle", -  "entityCount": 2, -  "attributeDetails": [ -    { -      "id": "http://example.org/vehicle/brandName", -      "type": "Attribute", -      "attributeName": "brandName", -      "attributeTypes": [ -        "Property" -      ] -    }, -    { -      "id": "http://example.org/vehicle/isParked", -      "type": "Attribute", -      "attributeName": "isParked", -      "attributeTypes": [ -        "Relationship" -      ] -    }, -    { -      "id": "https://uri.etsi.org/ngsi-ld/location", -      "type": "Attribute", -      "attributeName": "location", -      "attributeTypes": [ -        "GeoProperty" -      ] -    }, -    { -      "id": "http://example.org/vehicle/speed", -      "type": "Attribute", -      "attributeName": "speed", -      "attributeTypes": [ -        "Property" -      ] -    } -  ] -} -``` - -### C.5.10 Retrieve Available Attributes {#c.5.10tabretrieve-available-attributes number="15.5.10"} - -#### C.5.10.1 Introduction {#c.5.10.1tabintroduction number="15.5.10.1"} - -::: EX -EXAMPLE: - -Give back all attribute names for which entity instances are currently available in the NGSI-LD system that have an attribute with the respective name. -::: - -#### C.5.10.2 HTTP Request {#c.5.10.2tabhttp-request number="15.5.10.2"} - -::: B1 -**GET** /ngsi-ld/v1/attributes -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.10.3 HTTP Response {#c.5.10.3tabhttp-response number="15.5.10.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -  "id": "urn:ngsi-ld:AttributeList:56534657", -  "type": "AttributeList", -  "attributeList": [ -    "brandName", -    "isParked", -    "location", -    "speed", -    "http://example.org/parking/status" -  ] -} -``` - -::: NO -NOTE: - -The attribute names that can be found in the provided *\@context* are given as short names, the others as fully qualified names (FQNs). -::: - -### C.5.11 Retrieve Details of Available Attributes {#c.5.11tabretrieve-details-of-available-attributes number="15.5.11"} - -#### C.5.11.1 Introduction {#c.5.11.1tabintroduction number="15.5.11.1"} - -::: EX -EXAMPLE: - -Give back the details of all attributes for which entity instances are currently available in the NGSI-LD system to which an attribute with the respective attribute name belongs. -::: - -#### C.5.11.2 HTTP Request {#c.5.11.2tabhttp-request number="15.5.11.2"} - -::: B1 -**GET** /ngsi-ld/v1/attributes?details=true -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.11.3 HTTP Response {#c.5.11.3tabhttp-response number="15.5.11.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -[ -  { -    "id": "http://example.org/vehicle/brandName", -    "type": "Attribute", -    "attributeName": "brandName", -    "typeNames": [ -      "Vehicle" -    ] -  }, -  { -    "id": "http://example.org/vehicle/isParked", -    "type": "Attribute", -    "attributeName": "isParked", -    "typeNames": [ -      "Vehicle" -    ] -  }, -  { -    "id": "https://uri.etsi.org/ngsi-ld/location", -    "type": "Attribute", -    "attributeName": "location", -    "typeNames": [ -      "Vehicle", -      "OffStreetParking", -      "http://example.org/parking/ParkingSpot" -    ] -  }, -  { -    "id": "http://example.org/vehicle/speed", -    "type": "Attribute", -    "attributeName": "speed", -    "typeNames": [ -      "Vehicle" -    ] -  }, -  { -    "id": "http://example.org/parking/status", -    "type": "Attribute", -    "attributeName": "http://example.org/parking/status", -    "typeNames": [ -      "http://example.org/parking/ParkingSpot" -    ] -  } -]  -``` - -::: NO -NOTE: - -The attribute name and all type names that can be found in the provided *\@context* are given as short names, the others as Fully Qualified Names (FQNs). The *id* is always an FQN. -::: - -### C.5.12 Retrieve Available Attribute Information {#c.5.12tabretrieve-available-attribute-information number="15.5.12"} - -#### C.5.12.1 Introduction {#c.5.12.1tabintroduction number="15.5.12.1"} - -::: EX -EXAMPLE: - -Give back the details of the attribute named *brandName* (for which entity instances with an attribute of this name are currently available in the NGSI-LD system). -::: - -#### C.5.12.2 HTTP Request {#c.5.12.2tabhttp-request number="15.5.12.2"} - -::: B1 -**GET** /ngsi-ld/v1/attributes/brandName -::: - -::: B1 -[Alternative with FQN: **GET** /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName] -::: - -::: B1 -Accept: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.12.3 HTTP Response {#c.5.12.3tabhttp-response number="15.5.12.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -  "id": "http://example.org/vehicle/brandName", -  "type": "Attribute", -  "attributeName": "brandName", -  "attributeTypes": ["Property"], -  "typeNames": ["Vehicle"], -  "attributeCount": 2 -} -``` - -### C.5.13 Query Entities (Natural Language Filtering) {#c.5.13tabquery-entities-natural-language-filtering number="15.5.13"} - -#### C.5.13.1 Introduction {#c.5.13.1tabintroduction number="15.5.13.1"} - -::: EX -EXAMPLE: - -Give back all the Entities of type ["Vehicle"]{.HTML_Code} where the *marque* attribute in British English is ["Vauxhall Viva"]{.HTML_Code} . Only give back the *marque* attribute and provide the data in the NGSI-LD Simplified Format and only return language strings in German. -::: - -#### C.5.13.2 HTTP Request {#c.5.13.2tabhttp-request number="15.5.13.2"} - -::: B1 -**GET** /ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]== "Vauxhall Viva"&format =**simplified**&lang=de -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.13.3 HTTP Response {#c.5.13.3tabhttp-response number="15.5.13.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:A4567", -    "type": "Vehicle", -    "marque": "Opel Karl", -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.14 Temporal Query (Aggregated Representation) {#c.5.14tabtemporal-query-aggregated-representation number="15.5.14"} - -#### C.5.14.1 Introduction {#c.5.14.1tabintroduction number="15.5.14.1"} - -::: EX -EXAMPLE: - -Give back the maximum and average speed of Entities of type ["Vehicle"]{.HTML_Code} whose *brandName* attribute is not ["Mercedes"]{.HTML_Code} between the 1 ^st^ of August at noon and the 1 ^st^ of August at 01 PM, aggregated by periods of 4 minutes. -::: - -#### C.5.14.2 HTTP Request {#c.5.14.2tabhttp-request number="15.5.14.2"} - -::: B1 -**GET** /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=**aggregatedValues** -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.14.3 HTTP Response {#c.5.14.3tabhttp-response number="15.5.14.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "speed": { -      "type": "Property", -      "max": [ -        [ -          120, -          "2018-08-01T12:00:00Z", -          "2018-08-01T12:04:00Z" -        ], -        [ -          100, -          "2018-08-01T12:04:00Z", -          "2018-08-01T12:08:00Z" -        ] -      ], -      "avg": [ -        [ -          120, -          "2018-08-01T12:00:00Z", -          "2018-08-01T12:04:00Z" -        ], -        [ -          90, -          "2018-08-01T12:04:00Z", -          "2018-08-01T12:08:00Z" -        ] -      ] -    }, -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -``` - -### C.5.15 Scope Queries {#c.5.15tabscope-queries number="15.5.15"} - -#### C.5.15.1 Introduction {#c.5.15.1tabintroduction number="15.5.15.1"} - -::: EX -EXAMPLE: - -Give back all the Entities of type " [OffStreetParking"]{.HTML_Code} that are within the Scope [/Madrid/Centro]{.HTML_Code} or [/Madrid/Cortes]{.HTML_Code} . -::: - -#### C.5.15.2 HTTP Request {#c.5.15.2tabhttp-request number="15.5.15.2"} - -::: B1 -**GET** /ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes" -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.15.3 HTTP Response {#c.5.15.3tabhttp-response number="15.5.15.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -``` json -[ -   { -      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -      "type": "OffStreetParking", -      "scope": "/Madrid/Centro", -      "name": { -         "type": "Property", -         "value": "Downtown One" -      }, -      "availableSpotNumber": { -         "type": "Property", -         "value": 121, -         "observedAt": "2017-07-29T12:05:02Z", -         "reliability": { -            "type": "Property", -            "value": 0.7 -         }, -         "providedBy": { -            "type": "Relationship", -            "object": "urn:ngsi-ld:Camera:C1" -         } -      }, -      "totalSpotNumber": { -         "type": "Property", -         "value": 200 -      }, -      "location": { -         "type": "GeoProperty", -         "value": { -            "type": "Point", -            "coordinates": [ -               -8.5, -               41.2 -            ] -         } -      }, -      "@context": [ -         "http://example.org/ngsi-ld/latest/parking.jsonld", -         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -      ] -   }, -   { -      "id": "urn:ngsi-ld:OffStreetParking:Corte4", -      "type": "OffStreetParking", -      "scope": [ -            "/Madrid/Cortes", -            "/Company894/UnitC" -      ], -      "name": { -         "type": "Property", -         "value": "Corte4" -      }, -      "availableSpotNumber": { -         "type": "Property", -         "value": 121, -         "observedAt": "2017-07-29T12:05:02Z", -         "reliability": { -            "type": "Property", -            "value": 0.7 -         }, -         "providedBy": { -            "type": "Relationship", -            "object": "urn:ngsi-ld:Camera:C1" -         } -      }, -      "totalSpotNumber": { -         "type": "Property", -         "value": 100 -      }, -      "location": { -         "type": "GeoProperty", -         "value": { -            "type": "Point", -            "coordinates": [ -               -8.6, -               41.3 -            ] -         } -      }, -      "@context": [ -         "http://example.org/ngsi-ld/latest/parking.jsonld", -         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -      ] -   } -] -``` - -### C.5.16 Temporal Scope Queries {#c.5.16tabtemporal-scope-queries number="15.5.16"} - -#### C.5.16.1 Introduction {#c.5.16.1tabintroduction number="15.5.16.1"} - -::: EX -EXAMPLE: - -Give back the *speed* of all the Entities of type ["Vehicle"]{.HTML_Code} that have been within the Scope [/Madrid/Centro]{.HTML_Code} between the 1 ^st^ of August 2018 at noon and the 1 ^st^ of August 2018 at 01 PM. Note that the value of the Scope has to match for the given timeframe, which means it is possible that it has been set before, e.g. on 1 ^st^ of August 2018 at 11 AM. -::: - -#### C.5.16.2 HTTP Request {#c.5.16.2tabhttp-request number="15.5.16.2"} - -::: B1 -**GET** /ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro" -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -#### C.5.16.3 HTTP Response {#c.5.16.3tabhttp-response number="15.5.16.3"} - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -Vehicle [B9211]{.HTML_Code} has already been within the Scope [/Madrid/Centro ]{.HTML_Code}before the beginning of the request interval, whereas Vehicle [A8311]{.HTML_Code} only entered the Scope within the request interval. Thus in the latter case only Property values are included that have been observed after the Scope has become valid. - -## C.6 Date Representation {#c.6tabdate-representation number="15.6"} - -In NGSI-LD, a *TemporalProperty* is represented only by its value, i.e. no sub-Properties of *TemporalProperty* nor sub-Relationships of *TemporalProperty* can be conveyed. In more formal language, a *TemporalProperty* does not allow reification. The term *TemporalProperty* has been reserved for non-reified structural timestamps (*observedAt*, *createdAt*, *modifiedAt*, *deletedAt*), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as *timeproperty* in Temporal Queries as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language). - -The following examples show how time values (*Date*, *Time*, or *DateTime*) can be represented in NGSI-LD as reified Properties. For a reified Property whose value is assigned the JSON type *Date, DateTime or Time*, one mechanism is to use the Property's *valueType* to hold the datatype (["Date"]{.HTML_Code}, ["Datetime"]{.HTML_Code} or ["Time"]{.HTML_Code}), as shown below: - -Alternatively the data can be a structured to use the JSON-LD *\@value* syntax structure, as shown below: - -A third alternative to achieve the same result would be to use JSON-LD "type coercion". With type coercion, values with a special data type are defined with *\@type* in the *\@context*. This enforces the correct type for any occurrence. Such an *\@context* fragment is shown below: - -The above does not work, when using the *\@context* to perform compaction, in the normalized and compact representation of NGSI-LD, due to reification of the Property, because in this case *testedAt* is a complex JSON object, which cannot be compacted to a *DateTime* type as the *\@context* specifies. Thus, the full URI *http://example.org/test/testedAt* is kept, instead of the short name *testedAt*. In summary, user *\@contexts* used for the normalized and compact NGSI-LD representation cannot use the JSON-LD type coercion feature. - -However, in the simplified (keyValue) representation case, such an *\@context* with the specification of *testedAt* could be used, as there is no reification. - -As a side note, when using the above *\@value* + *\@type* approach, since *type* is mapped to *\@type* in the NGSI-LD core *\@context*, JSON-LD compaction will result in the following compacted value, instead of the one shown above, because *\@type* is compacted to *type*: - -``` json -[ -  { -    "id": "urn:ngsi-ld:Vehicle:B9211", -    "type": "Vehicle", -    "scope": { -  "type": "Property", -      "values": [ -        [ -          "/Madrid/Centro", -          "2018-08-01T11:00:00Z" -        ] -  ] -    }, -    "speed": { -      "type": "Property", -      "values": [ -        [ -          30, -          "2018-08-01T12:03:00Z" -        ], -        [ -          60, -          "2018-08-01T12:05:00Z" -        ], -        [ -          50, -          "2018-08-01T12:07:00Z" -        ] -      ] -    }, -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  }, -  { -    "id": "urn:ngsi-ld:Vehicle:A8311", -    "type": "Vehicle", -    "scope": { -  "type": "Property", -      "values": [ -        [ -          [ -             "/Madrid/Centro", -             "/Company123/UnitA" -          ], -          "2018-08-01T12:10:00Z" -        ] -  ] -    }, -    "speed": { -      "type": "Property", -      "values": [ -        [ -          40, -          "2018-08-01T12:12:00Z" -        ], -        [ -          60, -          "2018-08-01T12:14:00Z" -        ], -        [ -          50, -          "2018-08-01T12:16:00Z" -        ] -      ] -    }, -    "@context": [ -      "http://example.org/ngsi-ld/latest/vehicle.jsonld", -      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -  } -] -{ -  "id": "urn:ngsi-ld:Vehicle:B9211", -  "type": "Vehicle", -  "testedAt": { -    "type": "Property", -    "value":"2018-12-04T12:00:00Z" -    "valueType": "DateTime" -  }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/vehicle.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -  "id": "urn:ngsi-ld:Vehicle:B9211", -  "type": "Vehicle", -  "testedAt": { -    "type": "Property", -    "value": { -      "@type": "DateTime", -      "@value": "2018-12-04T12:00:00Z" -    } -  }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/vehicle.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -"testedAt": { -  "@type": "https://uri.etsi.org/ngsi-ld/DateTime", -  "@id": "http://example.org/test/testedAt" -} -"value": { -  "type": "DateTime", -  "@value": "2018-12-04T12:00:00Z" -} -``` - -## C.7 \@context utilization clarifications {#c.7tabcontext-utilization-clarifications number="15.7"} - -When expanding or compacting JSON-LD terms, the JSON-LD *\@context* to be used is always the one provided in the current API request. For the benefit of users and implementers the following examples illustrate this concept. - -The scenario starts with the creation of an Entity using a JSON-LD *\@context* as follows: - -::: B1 -**POST** /ngsi-ld/v1/entities/ -::: - -::: B1 -Content-Type: application/ld+json -::: - -::: B1 -Content-Length: 200 -::: - -The content of the *\@context* utilized for the referred Entity creation (at http://example.org/ngsi-ld/latest/parking.jsonld) is as follows: - -At Entity creation time the implementation will perform the expansion of terms using the JSON-LD *\@context* depicted above. - -Now it is needed to retrieve our initial Entity. For retrieving such Entity, this time, a different JSON-LD *\@context* is going to be utilized, as follows: - -``` json -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "OffStreetParking", -  "name": { -    "type": "Property", -    "value": "Downtown One" -  }, -  "availableSpotNumber": { -    "type": "Property", -    "value": 121, -    "observedAt": "2017-07-29T12:05:02Z" -  }, -  "totalSpotNumber": { -    "type": "Property", -    "value": 200 -  }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -{ -"OffStreetParking": "http://example.org/parking/OffStreetParking", -"availableSpotNumber": "http://example.org/parking/availableSpotNumber", -"totalSpotNumber": "http://example.org/parking/totalSpotNumber", -"name": "http://example.org/parking/name" -} -{ -"OffP": "http://example.org/parking/OffStreetParking", -"ava": "http://example.org/parking/availableSpotNumber", -"total": "http://example.org/parking/totalSpotNumber" -} -``` - -This new *\@context*, even though it makes use of the same set of Fully Qualified Names, is defining new short strings as terms. The reasons for that could be multiple: to facilitate data consumption by clients, to save some bandwidth, to enable a more (or less) human-readable response payload body in a language different than English, etc. - -In this particular case, the result of the Entity retrieval will be as depicted below. It can be observed that the terms defined by the JSON-LD *\@context* **provided at retrieval time** are used to render the Entity content (compaction), and **not** the terms that were provided at creation time (which may be no longer known by the broker). - -It is also interesting to note that the *\@context* array of the response payload body contains, indeed, our header-supplied *\@context*: - -::: B1 -**GET** /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "OffP", -  "name": { -    "type": "Property", -    "value": "Downtown One" -  }, -  "ava": { -    "type": "Property", -    "value": 121, -    "observedAt": "2017-07-29T12:05:02Z" -  }, -  "total": { -  "type": "Property", -    "value": 200 - }, -  "@context": [ -    "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld", -    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -  ] -} -``` - -::: ondemand_PAR_space_after_3 -Another interesting case to note is the one when an *\@context* with no matching terms or no *\@context* at all is supplied. See the following example: -::: - -::: B1 -**GET** /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 -::: - -::: B1 -Accept: application/ld+json -::: - -``` json -{ -  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", -  "type": "http://example.org/parking/OffStreetParking", -  "http://example.org/parking/name": { -    "type": "Property", -    "value": "Downtown One" -  }, -  "http://example.org/parking/availableSpotNumber": { -    "type": "Property", -    "value": 121, -    "observedAt": "2017-07-29T12:05:02Z" -  }, -  "http://example.org/parking/totalSpotNumber": { -    "type": "Property", -    "value": 200 -  }, -  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -} -``` - -In this particular case it can be observed that the user names (Entity Type, Attributes) in the response payload body have not been compacted, and as a result the Fully Qualified Names are included. However, the core API terms have been compacted, as the Core *\@context* is always considered to be implicitly present if not specified explicitly (and that is why it is included in the JSON-LD response, as mandated by the specification). - -## C.8 Link header utilization clarifications {#c.8tablink-header-utilization-clarifications number="15.8"} - -The JSON-LD Specification [[2]](7-tabreferences.md#2) states clearly that **only one HTTP Link header** with the link relationship is required to appear. Such statement has implications in terms of providing the JSON-LD *\@context* when using the NGSI-LD API. The main implication is that if the *\@context* is a compound one, i.e. an *\@context* which references multiple individual *\@context,* served by resources behind different URIs, then a **wrapper** *\@context* has to be created and hosted. The final aim is that only one *\@context* is referenced from the JSON-LD Link header. This can be illustrated with an example: - -Imagine that it is desired to create an Entity providing *\@context* terms which are defined in two different JSON-LD \@context resources: - -::: B1plus -- http://example.org/vehicle/v1/vehicle-context.jsonld -- https://schema.org -::: - -If a developer wants to reference these two *\@context* resources from a Link header, a wrapper *\@context* can be easily created as follows: - -``` json -{ -   "@context": [ -       "http://example.org/vehicle/v1/vehicle-context.jsonld", -       "https://schema.org", -       "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -   ] -} -``` - -As such wrapper \@context needs to be referenced from a Link header by using a URI, then it will have to be hosted at some place on the Web. Usually, developers will host *\@context* using popular and simple solutions such as GitHub or GitLab pages. As a result, developers will be able to use *\@context* in queries or when using ["application/json"]{.HTML_Code} as main content type managed by their applications. - -It is a **good practice to include the Core** *\@context* in the wrapper *\@context* so it can be used, off-the-shelf, by external JSON-LD processing tools. However, it should be noted this is not necessary for NGSI-LD, as the Core *\@context* is always implicitly included. - -Then, using such wrapper *\@context*, (in our example hosted at *https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld*), the developer will be able to issue requests like: - -::: B1 -**POST** /ngsi-ld/v1/entities/ -::: - -::: B1 -Content-Type: application/json -::: - -::: B1 -Content-Length: 200 -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -``` json -{ -   "id": "urn:ngsi-ld:Vehicle:V1", -   "type": "Vehicle", - "builtYear": { - "type": "Property", -     "value": "2014" - }, -   "speed": { -     "type": "Property", -     "value": 121, - "observedAt": "2017-07-29T12:05:02Z" - } -} -``` - -::: B1 -201 Created -::: - -::: B1 -Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 -::: - -::: B1 -Link: < https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld >; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -::: B1 -**GET** /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 -::: - -::: B1 -Accept: application/ld+json -::: - -::: B1 -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -::: - -::: B1 -200 OK -::: - -::: B1 -Content-Type: application/ld+json -::: - -Observe that in this case the broker is responding with the same wrapper *\@context* in the Link header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is ["application/ld+json"]{.HTML_Code}). However, that could not be always the case, as there could be situations where the broker could need to provide a wrapper *\@context* hosted by itself, for instance, when there are inline *\@context* terms or when the Core *\@context* has not been previously included by the wrapper *\@context* (not recommended) provided within developer's requests. - -## C.9 \@context processing clarifications {#c.9tabcontext-processing-clarifications number="15.9"} - -JSON-LD Specification [[2]](7-tabreferences.md#2) says that "If a term is redefined within a context, all previous rules associated with the previous definition are removed". In addition, it is stated that "Multiple contexts may be combined using an array, which is processed in order". - -In contrast to the JSON-LD Specification, the NGSI-LD specification states that the Core *\@context* is protected and has to remain immutable. This essentially means that the Core *\@context* has final precedence and, therefore, is always to be processed as the last one in the *\@context* array. For clarity, data providers should place the Core *\@context* in the final position. From the point of view of Data providers, care has to be taken so that there are no unexpected or undesired term expansions. See the following example: - -The problem of the example above is that the term ["]{.HTML_Code}[location]{.HTML_Code}["]{.HTML_Code} is defined in both the Core *\@context* and the schema.org user *\@context* and the Core *\@context* takes precedence for the expansion. In these situations, if one wanted to refer to the schema.org ["location"]{.HTML_Code}, the solution is to prefix the conflicting terms, so that there cannot be any clashing. Therefore, if the intent is to refer to throughout, the example above can be modified as shown below: - -Note that the Core *\@context* should be placed in the last position of the *\@context* array. NGSI-LD implementations are required to render content following this approach, which has been undertaken in order to maximize compatibility with JSON-LD processing tools. This example works because the ["schema:"]{.HTML_Code} prefix has already been defined by the schema.org *\@context*. - -## C.10 ValueType datatype utilization clarifications {#c.10tabvaluetype-datatype-utilization-clarifications number="15.10"} - -Using JSON-LD [[2]](7-tabreferences.md#2) syntax, typed values can be expressed using the JSON-LD *\@type* keyword when defining a term, where *\@type* value holds a URI which indicates the value's datatype. However, it can be desirable for a [Context Broker]{.HTML_Keyboard} to be able to hold simpler untyped values within a Property's *value* attribute and separately use a Property's *valueType* to hold the value's datatype. This format can be used to accommodate multiple acceptable datatype formats for the data to be held within a single Property and still hold sufficient meta data to be able to distinguish between them. - -For example, consider an ontology for an Entity of type ["Place"]{.HTML_Code} which has an *address* Property, where the *address* Property can **either** be an unstructured address in the form of a ["String" ]{.HTML_Code}**or** a structured ["PostalAddress"]{.HTML_Code} JSON Object with *street*, *city* and *country* attributes - the following JSON-LD schema can be defined: - -**Example JSON-LD schema** - -Then the following two Entities of type ["Place"]{.HTML_Code}can be created using the *address*.*valueType* Property to distinguish between the two formats: - -``` json -{ -   "id": "urn:ngsi-ld:Vehicle:V1", -   "type": "Vehicle", - "builtYear": { - "type": "Property", -     "value": "2014" - }, -   "speed": { -     "type": "Property", -     "value": 121, - "observedAt": "2017-07-29T12:05:02Z" - }, -    "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld" -} -{ -   "id": "urn:ngsi-ld:Building:B1", -   "type": "Building", - "name": { - "type": "Property", -     "value": "Empire State" - }, -   "location": { -     "type": "Property", -     "value": "20 West 34th Street, New York City, NY 10001" - }, -    "@context": [ -        "https://schema.org/version/latest/schemaorg-current-https.jsonld", -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -} -{ -    "id": "urn:ngsi-ld:Building:B1", -    "type": "Building", -    "name": { -        "type": "Property", -        "value": "Empire State" -    }, -    "schema:location": { -        "type": "Property", -        "value": "20 West 34th Street, New York City, NY 10001" -    }, -    "@context": [ -        "https://schema.org/version/latest/schemaorg-current-https.jsonld", -        "http://example.org/ngsi-ld/latest/parking.jsonld", -        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" -    ] -} -{ -    "example": "http://example.org/", -    "xsd": "http://www.w3.org/2001/XMLSchema#", - "address": "example:address", - "city": "example:city", - "country": "example:country", - "street": "example:street", - "Place": "example:Place" - "PostalAddress": "example:PostalAddress", -    "String": "xsd:String" -} -[ -    { -        "id": "urn:ngsi-ld:Place:27182", -        "type": "Place", -        "address": { -            "type": "Property", -            "value": "Pariser Platz, Berlin, Germany", -            "valueType": "String" -        } -    }, -    { -        "id": "urn:ngsi-ld:Place:31415", -        "type": "Place", -        "address": { -            "type": "Property", -            "value": { -                "street": "Straße des 17. Juni", -                "city": "Berlin", -                "country": "Germany" -            },            "valueType": "PostalAddress" -        } -    } -] -``` - -## C.11 Entity with digital signature for a Property {#c.11tabentity-with-digital-signature-for-a-property number="15.11"} - -As specified in [[35]](7-tabreferences.md#35), the atomic piece of information that creators can digitally sign in an NGSI-LD ecosystem is each single Attribute of an Entity. In the following example, an Entity of type "Store" with two Properties, "address" and "location" is presented. The "address" Property is digitally signed. The signature is created using one Ed25519 instantiation of the Edwards-Curve Digital Signature Algorithm (EdDSA).The used crypto suite is "eddsa-rdfc-2022". - -::: EX -EXAMPLE: - -Entity of type "Store" with two Properties. The "address" Property is digitally signed. - -``` json -{ -"id": "urn:ngsi-ld:Store:002", -"type": "Store", -"address": { -"type": "Property", -"value": { -"streetAddress": ["Tiger Street 4", "al"], -"addressRegion": "Metropolis", -"addressLocality": "Cat City", -"postalCode": "42420" -} -"ngsildproof": { -"type": "Property", -"entityIdSealed": "urn:ngsi-ld:Store:002", -"entityTypeSealed": "Store", -"value": { -"type": "DataIntegrityProof", -"created": "2025-01-27T21:02:24Z", -"verificationMethod": -"https://example.edu/issuers/565049#z6MkwXG2WjeQnN....Hc6SaVWoT", -"cryptosuite": "eddsa-rdfc-2022", -"proofPurpose": "assertionMethod", -"proofValue": -"z3XrH3diVCqpVHXkE7WbnictqyQCkJBGTx....NRTzmuoWU1Y2FyqGfSV9eS" -} -} -}, -"location": { -"type": "GeoProperty", -"value": { -"type": "Point", -"coordinates": [57.5522, -20.3484] -} -}, -"@context": "https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld" -} -``` -::: diff --git a/API-md/16-annex-d-informative-transformation-algorithms.md b/API-md/16-annex-d-informative-transformation-algorithms.md deleted file mode 100644 index 5f83974ffc6cfd29dfbfb92afd37cffa95d4c26c..0000000000000000000000000000000000000000 --- a/API-md/16-annex-d-informative-transformation-algorithms.md +++ /dev/null @@ -1,210 +0,0 @@ -# Annex D (informative): Transformation Algorithms {#annex-d-informative-transformation-algorithms number="16"} - -## D.1 Introduction {#d.1tabintroduction number="16.1"} - -These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification [[2]](7-tabreferences.md#2)). - -## D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) {#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1 number="16.2"} - -This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated *\@context*) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model. - -::: NO -NOTE: - -An early implementation of this algorithm can be found at [[i.5]](7-tabreferences.md#i.5). -::: - -Let: - -::: B1plus -- **G** be a graph defined as follows: -::: - -::: B2plus -- Let **N** be G's top level node. -- N is an Entity instance of type **T** or types **Ts**. Type name is "AliasT" or there is an Array of Type names ["AliasT1", ...,"AliasTn"], N's identifier is **I**. -- N has 0 or more associated Property. Each Property (**Psi**) is defined as follows: -::: - -::: B3plus -- Property type identifier is **Pi**. -- Property name is "AliasPi". -- Property Value is **Vi**. -- Property Value's associated data type is **Di**. -::: - -::: B2plus -- N is the subject of 0 or more Relationship. Each Relationship is defined as follows: -::: - -::: B3plus -- Relationship type identifier is **Ri**. -- Relationship name is "AliasRi". -- Relationship target object identifier is **Robji**. -::: - -::: B1plus -- **O** be a JSON object initialized to the empty object ({}). -- **C** be a JSON-LD *\@context* initialized as described by [annex B](14-annex-b-normative-core-ngsi-ld-context-definition.md#annex-b-normative-core-ngsi-ld-context-definition). -::: - -The algorithm should run as follows, provided all the preconditions defined above are satisfied: - -::: BN -1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> ... <"AliasTn", Tn>. -2. Add to O two new members: -::: - -::: B2 -a) <"id", I>. -::: - -::: B2 -b) <"type", "AliasT"> or <"type", ["AliasT1", ...,"AliasTn"]> .">. -::: - -::: BN -3. For each Property Psi (Pi, "AliasP", Vi, Di) associated to N: -::: - -::: B2 -a) Run Algorithm *ALG1.1* taking the following inputs: -::: - -::: B3plus -- Ps → Psi. -- O → O. -- C → C. -::: - -::: BN -4. For each Relationship Rs (Ri, AliasRi, Robji) associated to N: -::: - -::: B2 -a) Run Algorithm *ALG1.2* taking the following inputs: -::: - -::: B3plus -- Rs → Rsi. -- O → O. -- C → C. -::: - -::: BN -5. Return (O, C) and end of the algorithm. -::: - -## D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1) {#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1 number="16.3"} - -Let **Ps** be the Property that has to be transformed. It is defined by (P, "AliasP", V, D), where **P** denotes a Property Type Id, "**AliasP**" is the Property name, **V** is the Property Value and **D** is the Property Value's data type. - -Ps might be associated to extra Properties or Relationships. - -Let O be the output JSON-LD object and C the associated JSON-LD context: - -::: BN -1. Execute the following steps: -::: - -::: B2 -a) If no member with "AliasP" is present in O, add a new member to O with key "AliasP" and value an object structure, let it be named **Op** as defined in the following. Otherwise, add all existing members with "AliasP" to a JSON-LD array and in addition put the object structure Op as defined in the following: -::: - -::: B3plus -- <"type", "Property">. -- If D is not a native JSON data type add a new member to Op with name "value" and which value has to be an object structure as follows: -::: - -::: B4 -1) <"@type", D>. -::: - -::: B4 -2) <"@value", V>. -::: - -::: B3plus -- Else If D is a native JSON data type add a new member to Op as follows: -::: - -::: B4 -1) <"value", V>. -::: - -::: B2 -b) Add a new member to C as follows: -::: - -::: B3plus -- <"AliasP", P>. -::: - -::: B2 -c) For each Property associated to Ps (Pss) recursively run the present algorithm (*ALG1.1*) taking the following inputs: -::: - -::: B3plus -- Ps → Pss. -- O → Op. -- C → C. -::: - -::: B2 -d) For each Relationship associated to Ps (Rss) run algorithm *ALG1.2* taking the following inputs: -::: - -::: B3plus -- Rs → Rss. -- O → Op. -- C → C. -::: - -::: BN -6. Return (O,C) and end of the algorithm. -::: - -## D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2) {#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2 number="16.4"} - -Let **Rs** be the Relationship that has to be transformed. It is defined by (R, "AliasR", Robj), where **R** denotes a Relationship Type Id, "**AliasR**" is the Relationship's name and **Robj** is the identifier of the target object of the Relationship. - -Rs might be associated to extra Properties or Relationships. - -Let O be the output JSON-LD object and C the current JSON-LD context: - -::: BN -1. Execute the following statements: -::: - -::: B2 -a) If no member with "AliasR" is present in O, add a new member to O with key "AliasR" and value an object structure, let it be named **Or**, and defined as in the following. Otherwise, add all existing members with "AliasR" to a JSON-LD array and in addition put the object structure Or as defined in the following: -::: - -::: B3plus -- <"object", Robj>. -- <"type", "Relationship">. -::: - -::: B2 -b) For each Property associated to Rs (Pss) run the algorithm *ALG1.1* taking the following inputs: -::: - -::: B3plus -- Ps → Pss. -- O → Or. -- C → C. -::: - -::: B2 -c) For each Relationship associated to Rs (Rss) recursively run the present algorithm *ALG1.2* taking the following inputs: -::: - -::: B3plus -- Rs → Rss. -- O → Or. -- C → C. -::: - -::: BN -7. Return (O,C) and end of the algorithm. -::: diff --git a/API-md/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.md b/API-md/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.md deleted file mode 100644 index d5618bd3963a23d4c1334ff63d126b4b291dfefd..0000000000000000000000000000000000000000 --- a/API-md/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.md +++ /dev/null @@ -1,3 +0,0 @@ -# Annex E (informative): RDF-compatible specification of NGSI-LD meta-model {#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model number="17"} - -The content of this annex is now in ETSI GS CIM 006 [[i.8]](7-tabreferences.md#i.8). diff --git a/API-md/18-annex-f-informative-conventions-and-syntax-guidelines.md b/API-md/18-annex-f-informative-conventions-and-syntax-guidelines.md deleted file mode 100644 index 27907e9cc2d73e6ebe24bc6e9931c969ea5c0f9b..0000000000000000000000000000000000000000 --- a/API-md/18-annex-f-informative-conventions-and-syntax-guidelines.md +++ /dev/null @@ -1,69 +0,0 @@ -# Annex F (informative): Conventions and syntax guidelines {#annex-f-informative-conventions-and-syntax-guidelines number="18"} - -When new terms are defined, they are marked in bold, and terms are capitalized thereafter. - -::: EX -EXAMPLE 1: - -**NGSI-LD Linked Entity** , [Linked Entity]{.HTML_Keyboard} . -::: - -API Parameter names are always in lowercase. - -::: EX -EXAMPLE 2: - -*options* . -::: - -Entity Types are defined using lowercase but with a starting capital letter. - -::: EX -EXAMPLE 3: - -Vehicle, Building, ParkingSpace. -::: - -JSON-LD nodes and terms are always defined using camel case notation starting with lower case. - -::: EX -EXAMPLE 4: - -*createdAt* , *value* , *unitCode* . -::: - -When referring to special terms, data types or words defined previously in the present document or by other referenced specifications, italics format is used. - -::: EX -EXAMPLE 5: - -*ListRelationship, GeoProperty, Geometry, Second, Number* . -::: - -When referring to literal strings double quotes are used. - -::: EX -EXAMPLE 6: - -["application/json"]{.HTML_Code} , ["Subscription"]{.HTML_Code} . -::: - -When referring to the JSON-LD Context the mnemonic text string *\@context* is used as a placeholder. - -All the dates and times are given in UTC format. - -::: EX -EXAMPLE 7: - -[2018-02-09T11:00:00Z]{.HTML_Code} . -::: - -The measurement units used in the API are those defined by the International System of Units. - -::: EX -EXAMPLE 8: - -The distance in geo-queries is provided in meters. -::: - -When defining application-specific elements or API extensions the same conventions and syntax guidelines should be followed. diff --git a/API-md/19-annex-g-informative-localization-and-internationalization-support.md b/API-md/19-annex-g-informative-localization-and-internationalization-support.md deleted file mode 100644 index c10ea7bbbfd6f968365a899908795eea1a89cf27..0000000000000000000000000000000000000000 --- a/API-md/19-annex-g-informative-localization-and-internationalization-support.md +++ /dev/null @@ -1,177 +0,0 @@ -# Annex G (informative): Localization and Internationalization Support {#annex-g-informative-localization-and-internationalization-support number="19"} - -## G.0 Foreword {#g.0tabforeword number="19.1"} - -These algorithms described below are informative, but NGSI-LD implementations should aim at either implementing them as they are described here or providing equivalent *\@context* elements for their payloads to provide interoperability with their internationalized context entities. - -## G.1 Introduction {#g.1tabintroduction number="19.2"} - -### G.1.0 Foreword {#g.1.0tabforeword number="19.2.1"} - -Since Internationalization is not core to context information management, any direct support within NGSI-LD systems is limited. [Annex G](19-annex-g-informative-localization-and-internationalization-support.md#annex-g-informative-localization-and-internationalization-support) proposes a series of best practices for maintaining, querying and displaying interoperable internationalized data. - -The content of the *\@context* utilized for the referred Entities within these examples uses pre-existing URNs used for internationalization and is as follows: - -### G.1.1 Associating an Entity with a Natural Language {#g.1.1tabassociating-an-entity-with-a-natural-language number="19.2.2"} - -Where a context Entity is associated with a single natural language, include a well-defined *Property* indicating the natural language of the content. For example an Event taking place in French may be defined as follows: - -### G.1.2 Associating a Property with a Natural Language {#g.1.2tabassociating-a-property-with-a-natural-language number="19.2.3"} - -Where a *Property* of a context entity can be associated to one more natural language, include additional metadata as a sub-Property of that Property. For example, a Hotel with booking forms available in English, French and German may be defined as follows: - -### G.1.3 Associating as equivalent entity {#g.1.3tabassociating-as-equivalent-entity number="19.2.4"} - -Where equivalent context entities in multiple natural languages exist, they may be associated with each other through the use of a one-to-many relationship, where each relationship holds an additional sub-Property indicating the natural language of the equivalent entities. - -For example, three Events (such as a walking tour which is available in English, French and German) may be associated to each other as follows: - -``` json -{ -"inLanguage": "http://schema.org/inLanguage", -"sameAs": "http://schema.org/sameAs" -} -{ -    "type": "Event", -    "id": "urn:ngsi-ld:Event:bonjourLeMonde", -    "name": { -        "type": "Property", -        "value": "Bonjour le Monde"  -    }, -    "description": { -         "type": "Property", -         "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple"  -    }, -    "inLanguage": { -        "type": "Property", -        "value": "fr"    -    } -} -{ -    "type": "Hotel, -    "id": "urn:ngsi-ld:Hotel:XXXXX", -    "name": { -        "type": "Property", -        "value": "Grand Hotel"  -    }, -    "bookingUrl": { -        "type": "Property", -        "value": [ -            "http://example.com/booking-in-french/",  -            "http://example.com/booking-in-english/",  -            "http://example.com/booking-in-german/" -        ], -        "inLanguage": {  -            "type": "Property",  -            "value": ["fr", "en", "de" ] -        } -    } -} -{ -    "type": "Event", -    "id": "urn:ngsi-ld:Event:bonjourLeMonde", -    "name": { -        "type": "Property", -        "value": "Bonjour le Monde"  -    }, -    "sameAs": [ -        { -            "type": "Relationship", -            "datasetId" : "urn:ngsi-ld:Relationship:1", -            "object": "urn:ngsi-ld:Event:helloWorld", -            "inLanguage": { -                    "type": "Property", -                    "value": "en"    -            } -        }, -        { -            "type": "Relationship", -            "object": "urn:ngsi-ld:Event:halloWelt", -            "inLanguage": { -                    "type": "Property", -                    "value": "de"    -            } -        } -    ] - } -``` - -## G.2 Natural Language Collation Support {#g.2tabnatural-language-collation-support number="19.3"} - -### G.2.0 Foreword {#g.2.0tabforeword number="19.3.1"} - -All strings within an NGSI-LD system are defined and sorted as a sequence of Unicode characters. As such there is no simple collation mechanism to query entities ignoring case, diacritic marks or matching diphthong single letters such as the German ["ö"]{.HTML_Code} to also match with ["oe"]{.HTML_Code}. - -Many databases support a degree of natural language support, in general collation support will always depend upon the underlying database and as such will vary from implementation to implementation. This therefore and cannot be standardized and exposed as part of the context information management API. Furthermore, collation is slow and processor intensive, and for massive systems is better achieved using a separate index. - -For systems that require it, this clause proposes a mechanism as an extension to a NGSI-LD [Context Broker]{.HTML_Keyboard} which can be modified and used to offer collation support to the natural language attributes found within context entities where necessary through creating, querying and maintaining an additional property of a property for collated attributes. - -### G.2.1 Maintain collations as metadata {#g.2.1tabmaintain-collations-as-metadata number="19.3.2"} - -::: B1plus -- Create a subscription on the attribute (e.g. *name*) -- Create a simple microservice to add/upsert a *name.collate* property-of-a-property using a simple function to strip all diacritic marks - for example: -::: - -::: B2 -[str.normalize("NFD").replace(/[\\u0300-\\u036f]/g, "").toLower()]{.HTML_Sample} -::: - -Other substitutions could be made where local spelling rules vary (for example different for German ö = oe). - -### G.2.2 Route language sensitive queries via a proxy {#g.2.2tabroute-language-sensitive-queries-via-a-proxy number="19.3.3"} - -Create a simple forwarding proxy around the NGSI-LD system. For any urls with a *q* param (and a *collate* flag) run a clean-up of the *q* param and amend the query string: - -The following request on the proxy: - -::: B1 -**GET** /ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name -::: - -is altered on the fly and is sent to the NGSI-LD system as shown: - -::: B1 -**GET** /ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22 -::: - -Once again, the substitutions to make to the query string will depend on the rules of the natural language to be supported. - -## G.3 Localization of Dates, Currency formats, etc. {#g.3tablocalization-of-dates-currency-formats-etc. number="19.4"} - -### G.3.0 Foreword {#g.3.0tabforeword number="19.4.1"} - -Context data entities are designed to be interoperable and therefore all dates are held as UTC dates, all currency amounts are held as JSON numbers (with the unitCode property-of-a-property available to hold the currency), etc. Localization should not occur within the context data entities themselves. Offering fully localized responses is not a concern of the NGSI-LD API. - -If localization support is necessary, a simple proxying a conversion mechanism could be used to amend the context data received from the NGSI-LD system before being passed to a third party system for display. - -### G.3.1 Localizing Dates {#g.3.1tablocalizing-dates number="19.4.2"} - -For example, if a system needs to display *DateTime* data in Islamic Date format - -The following request on the proxy: - -::: B1 -**GET** /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified -::: - -is forwarded unaltered and is sent to the NGSI-LD system as shown: - -::: B1 -**GET** /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified -::: - -The response from the NGSI-LD system is always in UTC format: - -And the proxy can be used to update this to the desired format: - -Using an internationalization script such as the following: - -``` json - {"date": "2020-09-28T17:13:39+02:00"} - {"date": "11 Safar, 1442 1:13:39PM"} -new Intl.DateTimeFormat("en-u-ca-islamic", {day: 'numeric', month: -'long',weekday: 'long',year : 'numeric'}).format(date); -``` - -It should be noted that post-localization, the transformed date is no longer valid NGSI-LD. diff --git a/API-md/2-foreword.md b/API-md/2-foreword.md deleted file mode 100644 index 143addd99918f703fdc7b59d38f1ad73f8909011..0000000000000000000000000000000000000000 --- a/API-md/2-foreword.md +++ /dev/null @@ -1,3 +0,0 @@ -# Foreword {#foreword number="2"} - -This Group Specification (GS) has been produced by ETSI Industry Specification Group (ISG) cross-cutting Context Information Management (CIM). diff --git a/API-md/20-annex-h-informative-suggested-actuation-workflows.md b/API-md/20-annex-h-informative-suggested-actuation-workflows.md deleted file mode 100644 index e8255cc4fa755840e198c54aa06160f22ca92a8e..0000000000000000000000000000000000000000 --- a/API-md/20-annex-h-informative-suggested-actuation-workflows.md +++ /dev/null @@ -1,371 +0,0 @@ -# Annex H (informative): Suggested actuation workflows {#annex-h-informative-suggested-actuation-workflows number="20"} - -## H.1 Actuators and feedback to the consumer {#h.1tabactuators-and-feedback-to-the-consumer number="20.1"} - -Actuators are things that can change their state (light on/off) or execute actions (move forward, detect face, etc.). - -There is currently no explicitly and precisely specified support for actuation in the NGSI-LD API. Thus, this clause describes some conventions that represent a proposed best-practice about how NGSI-LD API and data models can be used for the interaction between applications and actuators represented by NGSI-LD Entities. - -The conventions and approach described in this clause are not powerful enough to implement complex actuation jobs that depend on each other and, for instance, make actuation decisions conditional on the outcome of other actuations, unless that behaviour is implemented in a custom way within the application logic. The concept of a more evolved service execution logic, being a first-class citizen of the NGSI-LD API and able to offer more structured building blocks for actuation, is outside the scope of this annex. - -An NGSI-LD system that comprises an actuator and supports actuation workflows is represented as one or more NGSI-LD Entities, plus a [Context Broker]{.HTML_Keyboard}, a [Context Source]{.HTML_Keyboard} or a [Context Producer]{.HTML_Keyboard}, and a [Context Consumer]{.HTML_Keyboard}, which collaborate. - -The interaction between actuator and [Context Consumer]{.HTML_Keyboard} needs to be bidirectional. Thus, actuators are triggered by the reception of actuation-specific commands (e.g. "set the on state of the lamp to false", to turn the light off) that are encoded as NGSI-LD data, following a suggested data model. They respond with feedback, similarly encoded as NGSI-LD data. - -Command feedbacks may serve to control the maximum operations rate a controlling application needs to achieve, and different levels of feedback can be requested, by associating a specific Quality of Service value to the command: - -::: B1plus -- Some applications need high operation rate but no feedback. For this case a QoS = 0 can be used. The typical example is to control the arms of a robot with a joystick. -- Some applications need to be sure that the actuators actually received the command request or need to get back a payload in response to the command. In this case a QoS = 1 can be used. The typical case is switching on a light with confirmation, or request face-detection with consequent notification of matching events. -- Commands can either require a short or a long execution time. For commands with long execution time, the application may require a continuous status feedback. In this case a QoS = 2 can be used. The typical example is that of a door opening, where feedback continuously reports the current level (10 % open, 50 % open, etc.). -::: - -## H.2 Architecture for actuation {#h.2tabarchitecture-for-actuation number="20.2"} - -In this architecture, the application acts as [Context Consumer]{.HTML_Keyboard}, and the terms are used interchangeably. - -Commands are sent to the [Context Broker]{.HTML_Keyboard} by the [Context Consumer]{.HTML_Keyboard}, using the standard NGSI-LD API and a suggested convention for representing them. In turn, feedback about command execution is received by the [Context Consumer]{.HTML_Keyboard}, both as continuous status updates and/or a final command result. - -More specifically, the component that handles direct communication with the actuator is the [Context Source]{.HTML_Keyboard} or the [Context Producer]{.HTML_Keyboard}: it uses an actuator-specific protocol to control the actuator and get responses and updates from it, i.e. from the real system. Such [Context Source]{.HTML_Keyboard}*/Consumer* or [Context Producer]{.HTML_Keyboard}/Storage acting as a proxy or intermediary to the actuator is referred to, in the following, as Context Adapter. - -Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD command requests from the NGSI-LD [Context Broker]{.HTML_Keyboard} and send back command status and result to it, as well as using an actuator-specific protocol to communicate with the actuator. - -The NGSI-LD [Context Broker]{.HTML_Keyboard} is responsible for handling direct communication with the [Context Consumer]{.HTML_Keyboard}. - -Thus, to support actuation, there is a need to specify: - -::: B1plus -- Additional NGSI-LD Properties the NGSI-LD system has to have, in order to represent and manage command Request, Status, Result. -- A communication model that allows commands to flow in forward direction and feedback to flow in reverse. This communication model has to comprise a mapping, to be held within the NGSI-LD system, that is able to route the command requests to the appropriate handler within the Context Adapter and vice-versa. -::: - -::: FL -![](./media/image144.png){style="width:6.69192in;height:3.5913in"} -::: - -::: {#Figure_H.2-1 .TF} -Figure H.2-1: Architecture for actuation -::: - -## H.3 Structure of Commands and additional Properties {#h.3tabstructure-of-commands-and-additional-properties number="20.3"} - -### H.3.0 Introduction {#h.3.0tabintroduction number="20.3.1"} - -The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing the actuator's status, a set of additional, dedicated NGSI-LD Properties associated with: - -::: B1plus -- the list of available commands, i.e. the list of commands supported by the actuator; -- command endpoints, one for each command, that are used to send and receive command related messages and optionally hold state for the ongoing commands. -::: - -The structure of the commands needs to be specified, but not the internal format of their payloads. By using commands with a custom payload, one can support all kinds of operations, for example: - -::: B1plus -- ["set-on": "true"]{.HTML_Sample} -- ["detect-face": {"face-features": "...."}]{.HTML_Sample} -- ["move": "forward"]{.HTML_Sample} -::: - -The data model for command requests, status and responses has to include metadata such as the QoS of the command, its identifier, and the custom payload itself. - -Both the requests/responses and the list of commands the NGSI-LD system is able to support can be represented with additional NGSI-LD Properties, as follows. - -### H.3.1 Property for listing available commands {#h.3.1tabproperty-for-listing-available-commands number="20.3.2"} - -The additional Property dedicated to the list of available commands is as follows: - -``` json -"commands": { -  "type": "Property", -  "value": ["","", …, ""] -} -``` - -It is a *Property* whose value is an array of Strings, each string representing the unique name of a supported command. - -### H.3.2 Properties for command endpoints {#h.3.2tabproperties-for-command-endpoints number="20.3.3"} - -For each available command, a set of three endpoints is to be additionally created within the NGSI-LD system, by means of three dedicated Properties per command. The first endpoint will manage that command's requests, the second endpoint will manage its status, and the third endpoint will manage command's results. - -This convention dictates that: - -::: B1plus -- The NGSI-LD Property that manages requests has the same name as the command, e.g. [""]{.HTML_Code}. -- The NGSI-LD Property that manages results has the same name as the command plus the ["-RESULT"]{.HTML_Code} suffix. -- The NGSI-LD Property that manages status has the same name as the command plus the ["-STATUS"]{.HTML_Code} suffix. -::: - -Each endpoint can receive multiple requests or responses, and it supports queueing of messages. For example, the command *moveToLocation* may receive a sequence of requests that are to be stored in an array and orderly processed depending on the arrival timestamps. A number of respective responses may be produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD Property, exploits the multi-Attribute feature (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), as follows: - -**Command Request endpoint** - -**Command Status endpoint** - -**Command Result endpoint** - -``` json -"": { -  "datasetId": a URI uniquely identifying the specific command request -               (optional, if the use case does not need command queueing), -  "type":      "Property", -  "qos":       an Integer, representing the desired QoS (optional, default=0), -  "value":     custom parameters of the command (mandatory) -} -"-STATUS": { -  "datasetId": a URI uniquely identifying the specific status feedback message -               (optional, if the use case does not need queueing them), -  "type":      "Property", -  "value":     custom status of the command (mandatory) -} -"-RESULT": { -  "datasetId": a URI uniquely identifying the specific result feedback message -               (optional, if the use case does not need queueing them), -  "type":      "Property", -  "value":     custom result of the command (mandatory) -} -``` - -Usually, the Context Adapter (or the actuator behind it), upon receiving a command request with a specific *datasetId*, will then generate status and result with the same *datasetId*, so that, when the status/result is received by the application, it can link it back to the corresponding command that is generating the received feedback. The value of the request, status and result is generic, and it is up to the specific application to define useful values. As an example, the PackML language for the control of packaging machines defines a set of possible values for statuses during an actuation workflow. - -::: EX -EXAMPLE 1: - -An example follows, where the NGSI-LD system represents a simple actuator. The example shows the NGSI-LD Entity representing a light that can change colour by manipulation of its brightness, hue and saturation values; further, it is possible to turn the lamp on and off. Apart from the *id* and the *type* , the actuator entity has a set of regular properties that represent the current status of the lamp. In the example these are *colorRGB* and *is-on* . Then it has the conventional Property named *commands* , signalling that it supports four commands: ["turn-on"]{.HTML_Code} , ["set-saturation"]{.HTML_Code} , ["set-brightness"]{.HTML_Code} , ["set-hue"]{.HTML_Code} . Further, it has four (times three) additional properties serving the purpose of command endpoints. - -``` json -{ -  "id": "urn:ngsi-ld:pHueActuator:light1", -  "type": "Lamp", -  REGULAR PROPERTIES -  "colorRGB": {"type": "Property", "value": "0xABABAB"}, -  "is-on": {"type": "Property", "value": true}, -  AVAILABLE COMMANDS -  "commands": { -    "type": "Property", -    "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] -  } -  COMMAND ENDPOINTS -  "turn-on": {"type": "Property", "value": } -  "turn-on-STATUS": {"type": "Property", "value": } -  "turn-on-RESULT": {"type": "Property", "value": } -  "set-hue": ... -  "set-hue-STATUS": ... -  "set-hue-RESULT": ... -  … -} -``` -::: - -::: EX -EXAMPLE 2: - -The following example shows an NGSI-LD Entity Fragment that can be used as a command request to request that the lamp be turned off. - -``` json -{ -  "id": "urn:ngsi-ld:pHueActuator:light1", -  "type": "Lamp", -  "turn-on": {  -    "type": "Property", -    "qos": { -      "type": "Property", -      "value": 1 -    }, -    "value": false -  } -} -``` -::: - -::: EX -EXAMPLE 3: - -In the following example, the value of the command request is a more complex JSON Object, to show that complex actions can be conveyed by just one request. Further, the request has an identifier that makes it possible to enqueue it, together with other request that may arrive to the same command endpoint within a timespan. - -``` json -{ -  "id": "urn:ngsi-ld:pHueActuator:light1", -  "type": "Lamp", -  "set-hue": {  -    "type": "Property", -    "qos": { -      "type": "Property", -      "value": 1 -    }, -    "datasetId": "myapp:mycommand:1342", -    "value": {"red": "1 seconds", "green": "2 seconds"} -  } -} -``` -::: - -In summary, the suggested convention prescribes a *commands* property that contains a list of commands supported by the actuator. For each of these commands, the convention requires a command endpoint consisting of three properties, the name of the command, e.g. ["turn-on]{.HTML_Code}["]{.HTML_Code}, the status property, which is the name of the command with ["]{.HTML_Code}[-]{.HTML_Code}[STATUS]{.HTML_Code}["]{.HTML_Code} as suffix, and the result, which is the name of the command with ["-]{.HTML_Code}[RESULT"]{.HTML_Code} as suffix. Nevertheless, it is noted that such suffixes are just a convention to distinguish the endpoints. So far, two practical implementations exist, see clauses [H.5](20-annex-h-informative-suggested-actuation-workflows.md#h.5tabimplementation-of-the-subscription-based-actuation-workflow) and [H.6](20-annex-h-informative-suggested-actuation-workflows.md#h.6tabimplementation-of-the-registration-based-actuation-workflow), that adopt the general scheme of this convention, with minor deviations. In fact, this convention is derived as a generalization that leverages the full potential of NGSI-LD sub-Attributes and multi-Attributes. - -## H.4 Communication model {#h.4tabcommunication-model number="20.4"} - -### H.4.1 Possible communication models {#h.4.1tabpossible-communication-models number="20.4.1"} - -This convention can be leveraged by two different communication models: - -::: B1plus -- Subscription/notification, where both the application and the Context Adapter use NGSI-LD Subscriptions to have the command requests delivered to the appropriate handler within the Context Adapter and vice-versa. In this case the Context Adapter acts as a [Context Source]{.HTML_Keyboard} as well as a [Context Consumer]{.HTML_Keyboard}. -- Forwarding, which uses the NGSI-LD Registry and a Context Adapter able to federate itself with the [Context Broker]{.HTML_Keyboard} holding the actuator's Entity, as a means to deliver the commands. In this case the Context Adapter acts as a Context Storage as well as a [Context Producer]{.HTML_Keyboard}. -::: - -### H.4.2 Subscription/notification model {#h.4.2tabsubscriptionnotification-model number="20.4.2"} - -For the interaction to work, the Context Adapter, acting as a proxy to the actuator, subscribes to all command properties; in example 1 of [clause H.3.2](20-annex-h-informative-suggested-actuation-workflows.md#h.3.2tabproperties-for-command-endpoints), these are ["set-brightness"]{.HTML_Code}, ["set-saturation"]{.HTML_Code}, ["set-hue"]{.HTML_Code} and ["turn-on"]{.HTML_Code}. When the application, acting as the actuation client, updates the value of a command property, the Context Adapter will receive the notification with the new value. This will be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol. The application in turn can subscribe to the command status and the result. The Context Adapter updates the status of the actuation during the execution of the command, which is primarily relevant in the case of longer-lasting actuations, and finally updates the result once the actuation has been completed. If the application has subscribed to the status and result, it will receive the corresponding notifications. Independent of the command-related properties, the status of the actuator, held within its regular properties, will be updated. - -The detailed workflow is depicted in [Figure H.4.2‑1](20-annex-h-informative-suggested-actuation-workflows.md#Figure_H.4.2-1), and can be interpreted as follows: - -::: BN -1. Application updates *turn-on* command Property with ["value": true]{.HTML_Code} -2. Context Adapter gets notification of the new value *true* -3. Context Adapter updates *turn-on-STATUS* command Property with ["value": "PENDING"]{.HTML_Code} -4. Application gets notification of the new value ["PENDING"]{.HTML_Code} -5. Context Adapter updates *is-on* regular Property with ["value": true]{.HTML_Code} -6. Application gets notification with value: [true]{.HTML_Code} -7. Context Adapter updates *turn-on-RESULT* command Property with ["value": "OK"]{.HTML_Code} -8. Application gets notification with of the new value ["OK"]{.HTML_Code} -::: - -::: FL -![](./media/image145.png){style="width:6.69261in;height:3.4in"} -::: - -::: {#Figure_H.4.2-1 .TF} -Figure H.4.2-1: Steps of the actuation workflow using subscription/notification -::: - -### H.4.3 Forwarding model {#h.4.3tabforwarding-model number="20.4.3"} - -The forwarding model uses registrations and forwarding of requests. Actuation of commands is provisioned via registration(s) to the NGSI-LD Registry done by the Context Adapter that states "I am responsible for command property ". When the Application changes the value of a command property, first the NGSI-LD [Context Broker]{.HTML_Keyboard} asks to the NGSI-LD Registry whether the property is delegated to some other component. The NGSI-LD Registry knows that property of the Entity is delegated to the Context Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the other communication model, the request will then be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol. - -In this model, the NGSI-LD Entity is distributed over two different components, because some of its properties live in the [Context Brokers]{.HTML_Keyboard} and other properties live in the Context Adapter, as indicated in [Figure H.4.3‑1](20-annex-h-informative-suggested-actuation-workflows.md#Figure_H.4.3-1) with a dotted rectangle. - -The rest of the workflow, i.e. delivery of status and result messages to the application, is done similarly to the subscription/notification model. The detailed workflow is depicted in [Figure H.4.3‑1](20-annex-h-informative-suggested-actuation-workflows.md#Figure_H.4.3-1), and can be interpreted as follows: - -::: B1 -1) Application updates *turn-on* command Property with ["value": true]{.HTML_Code} -::: - -::: B1 -2a) [Context Broker]{.HTML_Keyboard} ask Registry where to forward the request -::: - -::: B1 -2b) [Context Broker]{.HTML_Keyboard} forwards request to Context Adapter -::: - -::: B1 -3) Context Adapter updates *turn-on-STATUS* command Property with ["value": "PENDING"]{.HTML_Code} -::: - -::: B1 -4) Application gets notification of the new value ["PENDING"]{.HTML_Code} -::: - -::: B1 -5) Context Adapter updates *is-on* regular Property with ["value": true]{.HTML_Code} -::: - -::: B1 -6) Application gets notification with value: [true]{.HTML_Code} -::: - -::: B1 -7) Context Adapter updates *turn-on-RESULT* command Property with ["value": "OK"]{.HTML_Code} -::: - -::: B1 -8) Application gets notification with of the new value ["OK"]{.HTML_Code} -::: - -::: FL -![](./media/image146.png){style="width:6.69289in;height:3.69565in"} -::: - -::: {#Figure_H.4.3-1 .TF} -Figure H.4.3-1: Steps of the actuation workflow using forwarding -::: - -## H.5 Implementation of the subscription-based actuation workflow {#h.5tabimplementation-of-the-subscription-based-actuation-workflow number="20.5"} - -The Fed4IoT project () leverages the NGSI-LD architecture and the subscription/notification workflow for actuation, in order to implement the concept of a Cloud of Things. It enables virtualization of existing IoT sensors/actuators through Virtual Things and IoT Brokers. IoT application developers can simply rent the Virtual Things and the Brokers their applications need. - -The Fed4IoT's Cloud of Things is named VirIoT (), and it is based on the concept of Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, NGSI-LD, etc.). - -In [Figure H.5‑1](20-annex-h-informative-suggested-actuation-workflows.md#Figure_H.5-1) a diagram shows how VirIoT implements the concept of a large-scale and distribute NGSI-LD system that leverages the architecture and the workflow convention described in [clause H.4.2](20-annex-h-informative-suggested-actuation-workflows.md#h.4.2tabsubscriptionnotification-model). - -::: FL -![](./media/image147.png){style="width:6.69277in;height:3.15652in"} -::: - -::: {#Figure_H.5-1 .TF} -Figure H.5-1: VirIoT implementation of the NGSI-LD system and actuation workflow -::: - -All components encapsulate requests in a neutral-format message that leverages NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data distribution system, all information and actuation commands are encoded as NGSI-LD entities, plus an additional "meta header" that is used by the MQTT to publish and subscribe in a broadcast fashion to multiple vThings, because the same virtual sensor can be used by multiple applications at the same time. - -For the actuation workflow, the "data" part of this message contains the command request, as specified in [clause H.3](20-annex-h-informative-suggested-actuation-workflows.md#h.3tabstructure-of-commands-and-additional-properties), but with an additional value key that is the "command notification uri" ([cmd-nuri]{.PL}), representing a location where feedback (status, result) should be sent by the ThingVisor. For example, the [cmd-nuri]{.PL} contains the "data_in" MQTT topic of the issuing vSilo, so that command feedbacks (status and results) are sent to it, only, instead of being broadcasted to all subscribing applications. - -VirIoT is agnostic to access control issues to a virtual actuator, since the relevant policies are implemented in the specific ThingVisor, which can grant tokens to execute actuation-commands to a subset of vSilos only, through preliminary exchange of specific actuation-commands (a kind of log-in). - -Fed4IoT has developed several different ThingVisors (Context Adapters for different sensors and hardware): for example, lamp systems and robot devices are virtualized through specific ThingVisors, and applications can control the lighting system of a rented conference room or control camera and position of a bot by adding related virtual actuators to their vSilo. - -## H.6 Implementation of the registration-based actuation workflow {#h.6tabimplementation-of-the-registration-based-actuation-workflow number="20.6"} - -The IoT Agent node library [[i.22]](7-tabreferences.md#i.22) introduces the concept of an IoT Agent, which is a component that lets a group of devices send their data to and be managed from a [Context Broker]{.HTML_Keyboard} using their own native protocols. Thus, it corresponds to the Context Adapter, and wires up the IoT devices so that measurements can be read and commands can be sent using NGSI-LD requests sent to an NGSI-LD compliant context [Context Broker]{.HTML_Keyboard}. - -IoT Agents already exist or are in development for many IoT communication protocols and data models. Examples include the following: - -::: B1plus -- IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON payload) and NGSI-LD -- IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and NGSI-LD -- IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an UltraLight2.0 payload) and NGSI-LD -- IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD -::: - -This implementation follows the communication model described in [clause H.4.3](20-annex-h-informative-suggested-actuation-workflows.md#h.4.3tabforwarding-model), as explained in [Figure H.6‑1](20-annex-h-informative-suggested-actuation-workflows.md#Figure_H.6-1). In this workflow: - -::: B1plus -- Requests between User and [Context Broker]{.HTML_Keyboard} use NGSI-LD -- Requests between [Context Broker]{.HTML_Keyboard} and IoT Agent use NGSI-LD -- Requests between IoT Agent and IoT Device use native protocols -- Requests between IoT Device and IoT Agent use native protocols -- Requests between IoT Agent and [Context Broker]{.HTML_Keyboard} use NGSI-LD -::: - -::: FL -[![](./media/image148.png){style="width:6.17003in;height:7.31647in"}]{style="position: relative; display: inline-flex;"} -::: - -::: {#Figure_H.6-1 .TF} -Figure H.6-1: IoT Agent node library implementation of the NGSI-LD system and actuation workflow -::: - -Provisioning of the devices will be carried out (via REST API) through IoT Agents, as well. This provisioning implies that, on the one hand, the corresponding entities (with their commands), that represent the devices, are generated in the [Context Broker]{.HTML_Keyboard} and, on the other hand, that the corresponding IoT Agent is configured for communication with the corresponding device, all in one provisioning step. Below, an example how to provision a device which supports start and stop commands is presented. - -``` json -{ -    "devices": [ -        { -            "device_id":   "device001", -            "entity_name": "urn:ngsi-ld:Device:001", -            "entity_type": "Device", -            "attributes": [ -                { "object_id": "s", "name": "isOpen", "type": "boolean" } -            ], -            "commands": [ -                { "name": "start", "type": "command" }, -                { "name": "stop", "type": "command" } -            ], -            "static_attributes": [ -                { "name": -                    { "type": "Text", "value": "Device:001 provision" } -                } -            ] -        } -    ] -} -``` diff --git a/API-md/21-annex-i-informative-change-history.md b/API-md/21-annex-i-informative-change-history.md deleted file mode 100644 index 912218292a5b82a2010732f2837fd58ae972148b..0000000000000000000000000000000000000000 --- a/API-md/21-annex-i-informative-change-history.md +++ /dev/null @@ -1,471 +0,0 @@ -# Annex I (informative): Change history {#annex-i-informative-change-history number="21"} - -::: TAL -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Date | Version | Information about changes | -+=======================+=======================+========================================================================================================================================================================================================================+ -| February 2020 | {TAC} | Early draft copied from API version 1.2.1 | -| | | | -| | 1.2.10 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| February 2020 | {TAC} | Unicode characters. Query Language syntax changes to Attribute path, and extension to accept specifying just Query or Geoquery when Querying Entities | -| | | | -| | 1.2.11 | Acknowledgements to EU projects. Lightweight Figures | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2020 | {TAC} | Extending to other interactions the above changes to query entities interaction | -| | | | -| | 1.2.12 | Changes to ABNF Query Language syntax to access complex objects value of properties more easily | -| | | | -| | | Generalized Notification Headers, in order to carry authentication etc., info | -| | | | -| | | Novel &option=count and associated Header to indicate number of Entities in response to a query | -| | | | -| | | Novel/entityOperations/query and/temporal/entityOperations/query endpoints to perform query via POST | -| | | | -| | | Clarified attrs URL parameter behaviour | -| | | | -| | | Support for Multiple Attributes | -| | | | -| | | Support for Multiple Tenants | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2020 | {TAC} | from 101r1: Multi-Attribute-Support-fix-in-4.5.5 | -| | | | -| | Candidate 1.2.13 | from 102r1: Batch_Operation_Error_Codes | -| | | | -| | | from 110r1: JSON-LD Validation clause | -| | | | -| | | from 112r1: IRI Support for International Characters | -| | | | -| | | from 115r2: More Core Context Changes | -| | | | -| | | from 130: Entity Types | -| | | | -| | | MQTT Notifications | -| | | | -| | | GeoJSON Representation | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 9 July 2020 | {TAC} | Technical Officer verifications for submission to editHelp! publication pre-processing | -| | | | -| | 1.3.1 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| August 2020 | {TAC} | New baseline towards v1.4.1 | -| | | | -| | 1.3.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| November 2020 | {TAC} | From 272r1: Support for natural languages via LanguageProperty; [annex G](19-annex-g-informative-localization-and-internationalization-support.md#annex-g-informative-localization-and-internationalization-support) | -| | | | -| | 1.3.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 319: Align [Table 6.8.3.2‑1](11-tabapi-http-binding.md#Table_6.8.3.2-1) with [clause 5.10.2](10-tabapi-operation-definition.md#tabquery-context-source-registrations) for query via attrs | -| | | | -| | 1.3.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 310r2: Dot vs. comma in DateTime | -| | | | -| | 1.3.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 309r1: Remove sentences referring to old multi attributes representation | -| | | | -| | 1.3.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 308r: id and type for JSON-LD compliance | -| | | | -| | 1.3.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 313r1: FIXES to Cross domain data model for LanguageProperties | -| | | | -| | 1.3.4 | Bug fixes and errata | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | From 275r3: Temporal Aggregation Functions | -| | | | -| | 1.3.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2020 | {TAC} | 1.3.5 with small typos corrected, approved as 1.4.0 | -| | | | -| | 1.4.0 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2021 | {TAC} | ETSI Technical Officer review for ETSI EditHelp publication pre-processing | -| | | | -| | 1.4.1 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2021 | {TAC} | Editorial Changes, clarifications added, better references, figures replacements and corrections, figures merged, typos, code indentation | -| | | | -| | 1.4.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2021 | {TAC} | Temporal Pagination | -| | | | -| | 1.4.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2021 | {TAC} | Clarified behaviour when multiple instances of the same Entity are in an input array | -| | | | -| | 1.4.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2021 | {TAC} | From 130r6: NGSI-LD Scope | -| | | | -| | 1.4.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2021 | {TAC} | From 143r6: Storing, managing and serving \@contexts | -| | | | -| | 1.4.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2021 | {TAC} | From 120r4: API structuring | -| | | | -| | 1.4.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2021 | {TAC} | From 156: Remove static elements from temporal representations | -| | | | -| | 1.4.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2021 | {TAC} | From 155: Existence query | -| | | | -| | 1.4.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2021 | {TAC} | From 152: Remove null value deletion | -| | | | -| | 1.4.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2021 | {TAC} | From 151: attrs missing in core context | -| | | | -| | 1.4.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2021 | {TAC} | ETSI Technical Officer review for ETSI EditHelp publication pre-processing | -| | | | -| | 1.5.1 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| November 2021 | {TAC} | First early draft after EditHelp publication of V1.5.1 to prepare next V1.6.1 publication | -| | | | -| | 1.5.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2022 | {TAC} | Concise representation | -| | | | -| | 1.5.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2022 | {TAC} | PUT/PATCH Entity | -| | | | -| | 1.5.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2022 | {TAC} | Distributed operations | -| | | | -| | 1.5.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2022 | {TAC} | From 99r6: Deletions and advanced notifications | -| | | | -| | 1.5.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2022 | {TAC} | From 106r1: Workflow for actuation | -| | | | -| | 1.5.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2022 | {TAC} | From 105r1: Context Source Info in Context Source Registration | -| | | | -| | 1.5.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2022 | {TAC} | From 93r1: default context clarification | -| | | | -| | 1.5.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| July 2022 | {TAC} | From 91r1: CR_on_Scope_ABNF_format | -| | | | -| | 1.5.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Juy 2022 | {TAC} | Final Technical Official check for EditHelp publication | -| | | | -| | 1.6.1 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2022 | {TAC} | New early draft: | -| | | | -| | 1.6.2 | corrected [Annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api)6 date representation | -| | | | -| | | from 149r3: generalized description of \@context in bullet lists | -| | | | -| | | Fixed usage of NGSI-LD Null in Attributes' definitions | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | From 188r2_Registration_Clarifications | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | From 182r2_Add_NGSI-LD_Roles_for_Context_Registration | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | From 156r2 VocabProperty/URI type coercion | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | 177r2 Clarify usage of Accept, Content-Type and Linked \@context when forwarding to partial [Context Brokers]{.HTML_Keyboard} | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | 178 Add Batch Query to Federation Ops | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | 183r1 Clarify Temporal query behaviour | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | 149r4 Forbid scoped and nested \@contexts | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | 023006 Fixing CSource registration example in C.3 | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | Fix: Tenants URI becomes String | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | Fix: POST-QUERY-COUNT-PAGINATION | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | Fix: CHECK-URI-PARAM | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2022 | {TAC} | Updated examples and text to context v1.7.jsonld | -| | | | -| | 1.6.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2023 | {TAC} | CIM(23)000006_Adding_previousValue_to_GeoProperty_type_definition | -| | | | -| | 1.6.6 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2023 | {TAC} | cSource -> CSource; "implementations shall do the following" | -| | | | -| | 1.6.6 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2023 | {TAC} | 000013r4_Updated_Distributed_Execution_Behaviour | -| | | | -| | 1.6.7 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2023 | {TAC} | CIM(22)000195r3_type_passing_for_M2M_callReviewed | -| | | | -| | 1.6.8 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2023 | {TAC} | Fixing URI🡪String datatypes | -| | | | -| | 1.6.9 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2023 | {TAC} | CIM(23)000053r1_Entity_Graph_Retrieval (for FIWARE SUMMIT) | -| | | | -| | 1.7.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2023 | {TAC} | 000056r2_APIv172_towards_v18.docx (for FIWARE SUMMIT) | -| | | | -| | 1.7.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2023 | {TAC} | From 25023r2: Use Temporal Evolution instead of Temporal Representation + Updated figures in [clause 5](10-tabapi-operation-definition.md#tabapi-operation-definition) and 6 | -| | | | -| | 1.7.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| November 2023 | {TAC} | From 68r5: Additional id only format and attribute projection via pick and omit | -| | | | -| | 1.7.5 | From 121r1: Relationship as Array | -| | | | -| | | From 123r1: URN Namespace Definitions | -| | | | -| | | From 149r3: Allow Broader Local Requests | -| | | | -| | | From 153r1: JsonProperty | -| | | | -| | | From 159: Bug fixed in CIM 009: GeoJSON responses in figures | -| | | | -| | | From 160: Replace Attribute fix | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2023 | {TAC} | From 164: Host alias /info Endpoint | -| | | | -| | 1.7.6 | From 154r2: EntityMap | -| | | | -| | | Updated figure in [clause 6.2](11-tabapi-http-binding.md#tabglobal-definitions-and-resource-structure) | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | From 168r1: 504 error instead of 503 in JSON-LD context endpoints | -| | | | -| | 1.7.7 | From 169r1: Allow forbidden characters | -| | | | -| | | From 170: Remove Scope from PATCH /attrs operations | -| | | | -| | | From 1005r2: URI for value of several attributes | -| | | | -| | | From 173r2: Clarify match in distributed operations | -| | | | -| | | From 174: Protect core context | -| | | | -| | | From 25002r2: API Issue #10 Filter on value with specific datasetId | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | From 164r5: fix Tenant in Host Alias (164) and /info/sourceIdentity Endpoint + figure | -| | | | -| | 1.7.8 | Updated figure in [clause 6.2](11-tabapi-http-binding.md#tabglobal-definitions-and-resource-structure) | -| | | | -| | | Updated figures in [clause 4.2](9-tabcontext-information-management-framework.md#tabngsi-ld-information-model) | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | CIM(24)000007r2_Query_Language_Extension_for_Linked_Entity_Retrieval | -| | | | -| | 1.7.9 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | Internal revision, cleanup | -| | | | -| | 1.7.10 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | FIX: CIM(24)000015_Projection_attributes_error_messaging | -| | | | -| | 1.7.10 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | FIX: CIM(24)000014r1_POST_Query_Parameters | -| | | | -| | 1.7.10 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | TO revision | -| | | | -| | 1.7.11 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2024 | {TAC} | ISG CIM revision and cleanup after TO revision. New keywords | -| | | | -| | 1.7.12 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| February 2024 | {TAC} | Footnotes in Tables | -| | | | -| | 1.7.13 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| February 2024 | {TAC} | Change of NGSILDTerm style to HTML Keyboard | -| | | | -| | 1.7.15 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| February 2024 | {TAC} | Added expiresAt to \@context serving | -| | | | -| | 1.7.16 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2024 | {TAC} | Published | -| | | | -| | 1.8.1 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | Clone of published | -| | | | -| | 1.8.2 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | Minor typos and style cleanup | -| | | | -| | 1.8.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | 000048_Fix_operations_allowing_sysAttrs.docx | -| | | | -| | 1.8.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | 000047r2_Accept_header_in_case_of_partial_success\_\_207\_.docx | -| | | | -| | 1.8.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | 000049r1_Clarify\_\_options\_\_allowed_for_POST_queries.docx | -| | | | -| | 1.8.3 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2024 | {TAC} | Track changes removed | -| | | | -| | 1.8.4 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2024 | {TAC} | TooLargeResponse | -| | | | -| | 1.8.5 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000036r1_Loop_Detection | -| | | | -| | 1.8.6 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000033r6_Backwards_Compatibility_Indicators | -| | | | -| | 1.8.7 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000027r5_Value_Type | -| | | | -| | 1.8.8 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000029_Purge_Entities | -| | | | -| | 1.8.9 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000028r4_Transient_Entity_bugfixed | -| | | | -| | 1.8.10 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2024 | {TAC} | CIM(24)000070_Additional_Updates_to_ExpiresAt\_\_Conformance_etc\_ | -| | | | -| | 1.8.11 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2024 | {TAC} | CIM(24)000076r8_Entity_Maps_and_Split_Entities | -| | | | -| | 1.8.12 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2024 | {TAC} | CIM(24)000108_Adding_Missing_Elements_in_Core_Context_and_Data_Types.zip | -| | | | -| | 1.8.13 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| October 2024 | {TAC} | Updated figures and new baseline and created Stable Draft out of this | -| | | | -| | 1.8.14 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| November 2024 | {TAC} | CIM(24)000128r1_Signed_Attributes_and_Scoped_Context | -| | | | -| | 1.8.15 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| December 2024 | {TAC} | VocabProperty instead of VocabularyProperty in C2.2 and [Table 5.2.35‑1](10-tabapi-operation-definition.md#Table_5.2.35-1) | -| | | | -| | 1.8.16 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2025 | {TAC} | Reordering table rows in alpha (almost) order | -| | | | -| | 1.8.17 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| January 2025 | {TAC} | Ngsildproof example and \@context. Switching to new \@context URI for v1.9 | -| | | | -| | 1.8.18 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| February 2025 | {TAC} | CIM(25)000005 temporal bounds \_clarifications_and_misc_fixes | -| | | | -| | 1.8.19 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2025 | {TAC} | CIM(24)000111r5_Ordered_Entites | -| | | | -| | 1.8.20 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2025 | {TAC} | CIM(24)000138r4_Snapshot | -| | | | -| | 1.8.21 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2025 | {TAC} | CLEAN. Removed all track changes. Comments to be still addressed | -| | | | -| | 1.8.22 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2025 | {TAC} | CIM(25)000011r1 Updated figures and text for Snapshots (clauses [5](10-tabapi-operation-definition.md#tabapi-operation-definition) and [6](11-tabapi-http-binding.md#tabapi-http-binding)) | -| | | | -| | 1.8.23 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| March 2025 | {TAC} | CIM(25)000012r1 Harmonize output and 203 | -| | | | -| | 1.8.24 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2025 | {TAC} | CIM(25)000014 GS_CIM_009_v1825_fixSubscriptions | -| | | | -| | 1.8.25 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2025 | {TAC} | CIM(25)000016 Explanation of valueType as data type | -| | | | -| | 1.8.26 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| April 2025 | {TAC} | CIM(25)000015 Precision Clarification + Harmonize captions in [clause 6](11-tabapi-http-binding.md#tabapi-http-binding) + addressing fixes requested in the comments | -| | | | -| | 1.8.27 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2025 | {TAC} | CIM(25)000023 Order Table rows + small editorial fixes + aggregation parameters for POST query | -| | | | -| | 1.8.28 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| May 2025 | {TAC} | Final review prior to EditHelp | -| | | | -| | 1.8.29 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| June 2025 | {TAC} | TO review: fuzzy figures, table numbering. Editorial: fixed core context and value in ngsildproof example | -| | | | -| | 1.8.30 | | -+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: diff --git a/API-md/22-history.md b/API-md/22-history.md deleted file mode 100644 index e96773689c7a9c095b657440c69b60f4cfd2e9f2..0000000000000000000000000000000000000000 --- a/API-md/22-history.md +++ /dev/null @@ -1,29 +0,0 @@ -# History {#history number="22"} - -::: ondemand_PAR_alignment_CENTER_space_before_3_space_after_3 -+:-----------------------:+:-----------------------:+:-----------------------:+ -| **Document history** | -+-------------------------+-------------------------+-------------------------+ -| V1.1.1 | January 2019 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.2.1 | October 2019 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.2.2 | February 2020 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.3.1 | August 2020 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.4.1 | February 2021 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.4.2 | April 2021 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.5.1 | November 2021 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.6.1 | August 2022 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.7.1 | June 2023 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.8.1 | March 2024 | Publication | -+-------------------------+-------------------------+-------------------------+ -| V1.9.1 | June 2025 | Publication | -+-------------------------+-------------------------+-------------------------+ -::: diff --git a/API-md/3-modal-verbs-terminology.md b/API-md/3-modal-verbs-terminology.md deleted file mode 100644 index c57d7f233731fd763150297865737c9f8a867ce7..0000000000000000000000000000000000000000 --- a/API-md/3-modal-verbs-terminology.md +++ /dev/null @@ -1,5 +0,0 @@ -# Modal verbs terminology {#modal-verbs-terminology number="3"} - -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](https://portal.etsi.org/Services/editHelp!/Howtostart/ETSIDraftingRules.aspx) (Verbal forms for the expression of provisions). - -"**must**" and "**must not**" are **NOT** allowed in ETSI deliverables except when used in direct citation. diff --git a/API-md/4-executive-summary.md b/API-md/4-executive-summary.md deleted file mode 100644 index 0aff012de1b8d9f6c3f8baf953c118c2811675a9..0000000000000000000000000000000000000000 --- a/API-md/4-executive-summary.md +++ /dev/null @@ -1,3 +0,0 @@ -# Executive summary {#executive-summary number="4"} - -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). diff --git a/API-md/5-introduction.md b/API-md/5-introduction.md deleted file mode 100644 index a589c24d9bda8d5f3effa74c6ce63be5a2110603..0000000000000000000000000000000000000000 --- a/API-md/5-introduction.md +++ /dev/null @@ -1,9 +0,0 @@ -# Introduction {#introduction number="5"} - -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]](7-tabreferences.md#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]](7-tabreferences.md#i.3) and FIWARE^®^ NGSIv2 [[i.9]](7-tabreferences.md#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. diff --git a/API-md/6-tabscope.md b/API-md/6-tabscope.md deleted file mode 100644 index 2b987e1c5f32040b16b23d3c7b6fb4c17fe416d9..0000000000000000000000000000000000000000 --- a/API-md/6-tabscope.md +++ /dev/null @@ -1,3 +0,0 @@ -# 1 Scope {#tabscope number="6"} - -The present document defines a standardized 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]](7-tabreferences.md#i.1) and other work items ETSI GR CIM 007 [[i.2]](7-tabreferences.md#i.2) and ETSI GS CIM 006 [[i.8]](7-tabreferences.md#i.8) on security and on the information model. The present document supersedes prior versions, including ETSI GS CIM 004 [[i.16]](7-tabreferences.md#i.16). diff --git a/API-md/7-tabreferences.md b/API-md/7-tabreferences.md deleted file mode 100644 index a66c8f5b6883ee7a5be81d0e75c281193d63db91..0000000000000000000000000000000000000000 --- a/API-md/7-tabreferences.md +++ /dev/null @@ -1,149 +0,0 @@ -# 2 References {#tabreferences number="7"} - -## 2.1 Normative references {#tabnormative-references number="7.1"} - -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 in the [ETSI docbox](https://docbox.etsi.org/Reference/). - -::: NO -NOTE: - -While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity. -::: - -The following referenced documents are necessary for the application of the present document. - -::: EX -[[1]](7-tabreferences.md#1) W3C^®^ Recommendation 25 February 2014: "[RDF Schema 1.1](https://www.w3.org/TR/2014/REC-rdf-schema-20140225/)". - -[[2]](7-tabreferences.md#2) W3C^®^ Recommendation 16 July 2020: "[JSON-LD 1.1 - A JSON-based Serialization for Linked Data](http://www.w3.org/TR/json-ld/)". - -[[3]](7-tabreferences.md#3) [IETF RFC 7231](https://www.rfc-editor.org/info/rfc7231): "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content". - -[[4]](7-tabreferences.md#4) [IETF RFC 7232](https://www.rfc-editor.org/info/rfc7232): "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests". - -[[5]](7-tabreferences.md#5) [IETF RFC 3986](https://www.rfc-editor.org/info/rfc3986): "Uniform Resource Identifier (URI): Generic Syntax". - -[[6]](7-tabreferences.md#6) [IETF RFC 8259](https://www.rfc-editor.org/info/rfc8259): "The JavaScript Object Notation (JSON) Data Interchange Format". - -[[7]](7-tabreferences.md#7) [IETF RFC 8288](https://www.rfc-editor.org/info/rfc8288): "Web Linking". - -[[8]](7-tabreferences.md#8) [IETF RFC 7946](https://www.rfc-editor.org/info/rfc7946): "The GeoJSON Format". - -[[9]](7-tabreferences.md#9) [IETF RFC 8141](https://www.rfc-editor.org/info/rfc8141): "Uniform Resource Names (URNs)". - -[[10]](7-tabreferences.md#10) [IETF RFC 7807](https://www.rfc-editor.org/info/rfc7807): "Problem Details for HTTP APIs". - -[[11]](7-tabreferences.md#11) [IEEE 1003.2™-1992](https://standards.ieee.org/ieee/1003.2/1408/): "IEEE Standard for Information Technology - Portable Operating System Interfaces (POSIX™) - Part 2: Shell and Utilities". - -[[12]](7-tabreferences.md#12) [IETF RFC 5234](https://www.rfc-editor.org/info/rfc5234): "Augmented BNF for Syntax Specifications: ABNF". - -[[13]](7-tabreferences.md#13) [Unicode^®^ Technical Standard #10](http://unicode.org/reports/tr10/): "Unicode Collation Algorithm". - -[[14]](7-tabreferences.md#14) [Open Geospatial Consortium Inc. OGC 06-103r4](https://portal.opengeospatial.org/files/?artifact_id=25355): "OpenGIS^®^ Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture". - -[[15]](7-tabreferences.md#15) [Codes for Units of Measure used in International Trade Revision 9](http://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_Rev9e_2014.xls). - -[[16]](7-tabreferences.md#16) [IETF RFC 7396](https://www.rfc-editor.org/info/rfc7396): "JSON Merge Patch". - -[[17]](7-tabreferences.md#17) [ISO 8601: 2019](https://www.iso.org/advanced-search/x/title/status/P/docNumber/8601/docPartNo/docType/0/langCode/ics/currentStage/true/searchAbstract/true/stage/stageDateStart/stageDateEnd/committee/sdg): "Date and time --- Representations for information interchange". - -[[18]](7-tabreferences.md#18) [IETF RFC 2818](https://www.rfc-editor.org/info/rfc2818): "HTTP Over TLS". - -[[19]](7-tabreferences.md#19) [IETF RFC 5246](https://www.rfc-editor.org/info/rfc5246): "The Transport Layer Security (TLS) Protocol Version 1.2". - -[[20]](7-tabreferences.md#20) [IANA Registry of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - -[[21]](7-tabreferences.md#21) [ECMA-262 Specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/): "ECMAScript^®^ 2022 language specification". - -[[22]](7-tabreferences.md#22) The Unicode Consortium: "[Unicode^®^ 15.0.0](https://www.unicode.org/versions/Unicode15.0.0/)". - -[[23]](7-tabreferences.md#23) [IETF RFC 3987](https://www.rfc-editor.org/info/rfc3987): "Internationalized Resource Identifiers (IRIs)". - -[[24]](7-tabreferences.md#24) OASIS Standard: "[MQTT Version 3.1.1 Plus Errata 01](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html)". Edited by Andrew Banks and Rahul Gupta. 10 December 2015. - -[[25]](7-tabreferences.md#25) OASIS Standard: "[MQTT Version 5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html)". Edited by Andrew Banks, Ed Briggs, Ken Borgendale and Rahul Gupta. 07 March 2019. - -[[26]](7-tabreferences.md#26) [IETF RFC 7240](https://www.rfc-editor.org/info/rfc7240): "Prefer Header for HTTP". - -[[27]](7-tabreferences.md#27) [IETF RFC 7230](https://www.rfc-editor.org/info/rfc7230): "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing". - -[[28]](7-tabreferences.md#28) [IETF RFC 5646](https://www.rfc-editor.org/info/rfc5646): "Tags for Identifying Languages". - -[[29]](7-tabreferences.md#29) [IETF RFC 3282](https://www.rfc-editor.org/info/rfc3282): "Content Language Headers". - -[[30]](7-tabreferences.md#30) [IETF RFC 7234](https://www.rfc-editor.org/info/rfc7234): "Hypertext Transfer Protocol (HTTP/1.1): Caching". - -[[31]](7-tabreferences.md#31) [IETF RFC 7233](https://www.rfc-editor.org/info/rfc7233): "Hypertext Transfer Protocol (HTTP/1.1): Range Requests". - -[[32]](7-tabreferences.md#32) IANA: "[Hypertext Transfer Protocol (HTTP) Warn Codes](https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml)". - -[[33]](7-tabreferences.md#33) [IETF RFC 6906](https://www.rfc-editor.org/info/rfc6906): "The 'profile' Link Relation Type". - -[[34]](7-tabreferences.md#34) W3C^®^ Recommendation 25 February 2014: "[RDF 1.1 Concepts and Abstract Syntax](https://www.w3.org/TR/rdf11-concepts)". - -[[35]](7-tabreferences.md#35) [ETSI GS CIM 019](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/019/): "cross-cutting Context Information Management (CIM); handling of provenance information in NGSI-LD". - -[[36]](7-tabreferences.md#36) [IETF RFC 6067](https://www.rfc-editor.org/info/rfc6067): "BCP 47 Extension U". - -[[37]](7-tabreferences.md#37) [ETSI GS CIM 047](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/047/): "Context Information Management (CIM); OpenAPI Specification for NGSI-LD API". -::: - -## 2.2 Informative references {#tabinformative-references number="7.2"} - -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. - -::: NO -NOTE: - -While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity. -::: - -The following referenced documents may be useful in implementing an ETSI deliverable or add to the reader's understanding, but are not required for conformance to the present document. - -::: EX -[[i.1]](7-tabreferences.md#i.1) [ETSI GR CIM 002 (V1.1.1)](https://www.etsi.org/deliver/etsi_gr/CIM/001_099/002/01.01.01_60/gr_CIM002v010101p.pdf): "Context Information Management (CIM); Use Cases (UC)". - -[[i.2]](7-tabreferences.md#i.2) [ETSI GR CIM 007](https://www.etsi.org/deliver/etsi_gr/CIM/001_099/007/): "Context Information Management (CIM); Security and Privacy". - -[[i.3]](7-tabreferences.md#i.3) [OMA-TS-NGSI_Context_Management-V1_0-20120529-A](http://www.openmobilealliance.org/release/NGSI/V1_0-20120529-A/OMA-TS-NGSI_Context_Management-V1_0-20120529-A.pdf): "NGSI Context Management". - -[[i.4]](7-tabreferences.md#i.4) ETSI TS 103 264 (V3.1.1): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping". - -[[i.5]](7-tabreferences.md#i.5) [NGSI-LD Wrapper](https://github.com/Fiware/NGSI-LD_Wrapper): "Experimental proxy for adaptation between FIWARE^®^ and NGSI-LD". - -[[i.6]](7-tabreferences.md#i.6) Graph Databases: "New Opportunities for Connected Data". O'Reilly 2^nd^ Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892. - -[[i.7]](7-tabreferences.md#i.7) [JSON-LD Playground](https://json-ld.org/playground/): "Experimentation tool for JSON-LD". - -[[i.8]](7-tabreferences.md#i.8) [ETSI GS CIM 006](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/006/): "Context Information Management (CIM); Information Model (MOD0)". - -[[i.9]](7-tabreferences.md#i.9) [FIWARE^®^-NGSI v2 Specification](http://fiware.github.io/specifications/ngsiv2/stable/). - -[[i.10]](7-tabreferences.md#i.10) [IETF RFC 6902](https://www.rfc-editor.org/info/rfc6902): "JavaScript Object Notation (JSON) Patch". - -[[i.11]](7-tabreferences.md#i.11) [JSON Schema Validation: A Vocabulary for Structural Validation of JSON](https://json-schema.org/draft/2020-12/json-schema-validation.html). - -[[i.12]](7-tabreferences.md#i.12) [OpenAPI™ Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md). - -[[i.13]](7-tabreferences.md#i.13) [NGSI-LD JSON Schemas](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/schema). - -[[i.14]](7-tabreferences.md#i.14) [NGSI-LD OpenAPI™ Specification](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/spec). - -[[i.15]](7-tabreferences.md#i.15) [NGSI-LD Examples](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/examples). - -[[i.16]](7-tabreferences.md#i.16) ETSI GS CIM 004 (V1.1.2): "Context Information Management (CIM); Application Programming Interface (API)". - -[[i.17]](7-tabreferences.md#i.17) ETSI ISG CIM: "[NGSI-LD Status](https://docbox.etsi.org/ISG/CIM/Open/NGSI-LD%20Status.pdf)". - -[[i.18]](7-tabreferences.md#i.18) [Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32016R0679) on the protection of natural persons with regard to the processing of personal data and on the free movement of such data, and repealing Directive 95/46/EC (General Data Protection Regulation). - -[[i.19]](7-tabreferences.md#i.19) [MQTT URI Scheme](https://github.com/mqtt/mqtt.org/wiki/URI-Scheme). - -[[i.20]](7-tabreferences.md#i.20) [GeoJSON-LD 1.0](http://geojson.org/geojson-ld/). Base context for processing GeoJSON according to the JSON-LD processing model. - -[[i.21]](7-tabreferences.md#i.21) [ETSI GR CIM 008](https://www.etsi.org/deliver/etsi_gr/CIM/001_099/008/): "Context Information Management (CIM); NGSI-LD Primer". - -[[i.22]](7-tabreferences.md#i.22) [IoT Agent Library](https://github.com/telefonicaid/iotagent-node-lib). -::: diff --git a/API-md/8-tabdefinition-of-terms-symbols-and-abbreviations.md b/API-md/8-tabdefinition-of-terms-symbols-and-abbreviations.md deleted file mode 100644 index d5317f64633f3bd21a443fdef0bb342fd0a8538f..0000000000000000000000000000000000000000 --- a/API-md/8-tabdefinition-of-terms-symbols-and-abbreviations.md +++ /dev/null @@ -1,333 +0,0 @@ -# 3 Definition of terms, symbols and abbreviations {#tabdefinition-of-terms-symbols-and-abbreviations number="8"} - -## 3.1 Terms {#tabterms number="8.1"} - -For the purposes of the present document, the following terms apply: - -::: NO -NOTE 1: - -The letters "NGSI-LD" were added to most terms to confirm that they are distinct from other terms of similar/same name in use in other organizations, however, in the present document the letters "NGSI-LD" are generally omitted for brevity. -::: - -::: NO -NOTE 2: - -The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [[23]](7-tabreferences.md#23), which extends the use of characters to Unicode characters [[22]](7-tabreferences.md#22) beyond the ASCII character set, enabling the support of languages other than English. -::: - -**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]{.HTML_Keyboard} that only uses a local storage when serving NGSI-LD requests, without involving any external [Context Sources]{.HTML_Keyboard} - -**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]{.HTML_Keyboard} - -**NGSI-LD Context Registry:** software functional element where [Context Sources]{.HTML_Keyboard} register the information that they can provide - -::: NO -NOTE: - -It is used by [Distribution Brokers]{.HTML_Keyboard} and [Federation Brokers]{.HTML_Keyboard} to find the appropriate [Context Sources]{.HTML_Keyboard} which can provide the information required for serving an NGSI-LD request. -::: - -**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 - -::: NO -NOTE: - -It is usually registered with an NGSI-LD Registry so that it can announce what kind of information it can provide, when requested, to [Context Consumers]{.HTML_Keyboard} and Brokers. -::: - -**NGSI-LD Context Source Registration:** description of the information that can be provided by a [Context Source]{.HTML_Keyboard}, which is used when registering the [Context Source]{.HTML_Keyboard} with the [Context Registry]{.HTML_Keyboard} - -**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]{.HTML_Keyboard} that uses both local context information and registration information from an NGSI-LD [Context Registry]{.HTML_Keyboard}, to access matching context information from a set of distributed [Context Sources]{.HTML_Keyboard} - -**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 - -::: NO -NOTE: - -In the NGSI-LD API, any instance of such an entity is **uniquely identified by a URI** , and characterized by reference to one or more **NGSI-LD Entity Type(s)** . -::: - -**NGSI-LD Entity Map:** mapping of NGSI-LD Entity ids to Context Source Registrations used in maintaining atomicity of transactions performed by [Distribution Brokers]{.HTML_Keyboard} and [Federation Brokers]{.HTML_Keyboard} - -**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 - -::: NO -NOTE: - -In the NGSI-LD API, an NGSI-LD Entity Type is **uniquely identified by a URI** . -::: - -::: EX -EXAMPLE 1: - -["Vehicle"]{.HTML_Code} is an NGSI-LD Entity Type and is identified with a proper URI. -::: - -::: EX -EXAMPLE 2: - -Bob's private car whose plate number is ["ABCD1234"]{.HTML_Code} is an NGSI-LD Entity whose NGSI-LD Entity Type name is ["Vehicle".]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -Alice's motorhome has a unique URI as id, but can be assigned multiple NGSI-LD Entity types, e.g. ["Vehicle"]{.HTML_Code} and ["Home"]{.HTML_Code} . -::: - -**NGSI-LD External Linked Entity:** [Linked Entity]{.HTML_Keyboard} that is identified through a **dereferenceable URI** which does not exist within the current NGSI-LD system - -::: NO -NOTE: - -It can exist within another NGSI-LD system or within a non-NGSI-LD system. -::: - -::: EX -EXAMPLE: - -An NGSI-LD Entity, whose Entity Type name is ["Book"]{.HTML_Code} , can be externally linked, through the ["wasWrittenBy"]{.HTML_Code} relationship, to a resource identified by the URI ["http://dbpedia.org/resource/Mark_Twain"]{.HTML_Code} . -::: - -**NGSI-LD Federation Broker:** [Distribution Broker]{.HTML_Keyboard} that federates information from multiple underlying NGSI-LD [Context Brokers]{.HTML_Keyboard} 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]{.HTML_Keyboard} that exists within the current NGSI-LD system - -::: EX -EXAMPLE: - -An NGSI-LD Entity, whose Entity Type name is ["Vehicle",]{.HTML_Code} can be internally linked, through the ["isParkedAt" ]{.HTML_Code} relationship, to another NGSI-LD Entity, of Type name ["Parking"]{.HTML_Code} , identified by the URI ["urn:ngsi-ld:Parking:Downtown1"]{.HTML_Code} . -::: - -**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 - -::: NO -NOTE: - -The target value contains data which is not available for interpretation. -::: - -**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 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 - -::: EX -EXAMPLE: - -"A bus route services the following bus stops" can be represented by an NGSI-LD *ListRelationship* whose name is "route" which holds an array of directed links towards a series of NGSI-LD Entities of type (Type name) ["BusStop"]{.HTML_Code} . -::: - -**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 - -::: EX -EXAMPLE: - -"Bob's vehicle is currently parked on a street which is known as 'Grand Place' in French and 'Grote Markt' in Dutch" can be represented by an NGSI-LD LanguageProperty whose name is ["street"]{.HTML_Code} which holds an NGSI-LD Map of two key-value pairs containing both the French [("fr"]{.HTML_Code} ) and Dutch ( ["nl"]{.HTML_Code} ) exonyms of the street name. -::: - -**NGSI-LD Null:** ["urn:ngsi-ld:null"]{.HTML_Code} or [{"@none": "urn:ngsi-ld:null"} ]{.HTML_Code}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 - -::: EX -EXAMPLE: - -"Bob's vehicle's speed is 40 km/h" can be represented by an NGSI-LD Property, whose name is "speed", and which characterizes an NGSI-LD Entity, whose NGSI-LD Type is ["Vehicle"]{.HTML_Code} . [Such a name can be expanded to a fully qualified name in the form of a ]{.ondemand_CHAR_color_000000} URI [, for instance ]{.ondemand_CHAR_color_000000} ["http://example.org/Vehicle"]{.HTML_Code} or ["http://example.org/speed"]{.HTML_Code} . -::: - -**NGSI-LD Query:** collection of criteria used to select a sub-set of NGSI-LD Elements, matching the criteria - -**NGSI-LD Registry API:** part of the NGSI-LD API that is implemented by the [Context Registry]{.HTML_Keyboard}, including operations for registering [Context Sources]{.HTML_Keyboard} and managing [Context Source Registrations]{.HTML_Keyboard} (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 - -::: EX -EXAMPLE 1: - -An NGSI-LD Entity of type ["Vehicle"]{.HTML_Code} can be the subject of an NGSI-LD Relationship whose object is an NGSI-LD Entity of type ["Parking"]{.HTML_Code} . -::: - -::: EX -EXAMPLE 2: - -An NGSI-LD Entity of type ["Vehicle"]{.HTML_Code} can be the subject of an NGSI-LD Relationship whose object is an array of NGSI-LD Entities of type ["Passenger"]{.HTML_Code} . -::: - -**NGSI-LD Scope:** hierarchical structuring of Entities that enables restricting query results and notifications - -**NGSI-LD Snapshot:** set of NGSI-LD Entities, retrieved through one or more NGSI-LD Queries, which are locally persisted, providing a relatively consistent view of the situation when the queries were executed, and on which Context Consumers can execute further local NGSI-LD Operations - -**NGSI-LD Temporal API:** part of the NGSI-LD API pertaining to the [Temporal Evolution of Entities]{.HTML_Keyboard}, including operations for providing and managing the [Temporal Evolution of Entities]{.HTML_Keyboard} and Attributes, and operations for consuming the [Temporal Evolution of Entities]{.HTML_Keyboard} - -**NGSI-LD Temporal Evolution of an Entity:** sequence of values attributed to an [NGSI-LD Entity]{.HTML_Keyboard} 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]{.HTML_Keyboard} 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]{.HTML_Keyboard} (e.g. Entities, Subscriptions, [Context Source Registrations]{.HTML_Keyboard}) 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) - -::: EX -EXAMPLE: - -Bob's private car 'speed' NGSI-LD Value is the number 100 (kilometres per hour). -::: - -**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 - -::: EX -EXAMPLE: - -"Bob's car is a non-commercial vehicle" can be represented by an NGSI-LD [VocabProperty]{.HTML_Keyboard} whose name is ["category"]{.HTML_Code} which holds the string value ["non-commercial"]{.HTML_Code} . If the associated JSON-LD context defines the term ["non-commercial" ]{.HTML_Code} as ["http://example.com/non-commercial",]{.HTML_Code} then the returned value shall be expanded using JSON-LD type coercion into the URI the ["http://example.com/non-commercial"]{.HTML_Code} . -::: - -## 3.2 Symbols {#tabsymbols number="8.2"} - -Void. - -## 3.3 Abbreviations {#tababbreviations number="8.3"} - -For the purposes of the present document, the following abbreviations apply: - -ABNF Augmented Backus-Naur Form - -ALG1 ALGorithm for transforming an NGSI-LD Entity into a JSON-LD document - -AM Ante Meridiem - -API Application Programming Interface - -ASCII American Standard Code for Information Interchange - -BNF Backus Naur Form - -CH Switzerland - -CSR Context Source Registration - -ECMA European Computer Manufacturers Association - -EU European Union - -FI Future Internet - -FQN Fully Qualified Name - -GB Great Britain - -GDPR General Data Protection Regulation - -GeoJSON Geographic JavaScript Object Notation - -GeoJSON-LD Geographic JavaScript Object Notation - Linked Data - -GIS Geographic Information System - -GPS Global Positioning System - -HTTP Hypertext Transfer Protocol - -HTTPS Hypertext Transfer Protocol Secure - -IANA Internet Assigned Numbers Authority - -ID IDentifier - -IEEE Institute of Electrical and Electronics Engineers - -IETF Internet Engineering Task Force - -IoT Internet of Things - -IRI Internationalized Resource Identifier - -ISG Industry Specification Group - -ISO International Organization for Standardization - -JSON JavaScript Object Notation - -JSON-LD JSON Linked Data - -LD Linked Data - -LWM2M LightWeight Machine to Machine - -M2M Machine to Machine - -MIME Multi-purpose Internet Mail Extensions - -MQTT Message Queuing Telemetry Transport - -N/A Not Applicable - -NGSI Next Generation Service Interfaces - -NGSILD [Next Generation Service Interfaces Linked Data (same as NGSI-LD)]{.ondemand_CHAR_color_000000} - -NID Namespace IDentifier - -NSS Namespace Specific String - -OAS Open API Specification - -OMA Open Mobile Alliance - -oneM2M oneM2M Partnership Project - -PM Post Meridiem - -POSIX Portable Operating System Interface - -QoS Quality of Service - -RDF Resource Description Format - -REST REpresentational State Transfer - -RFC Request For Comments - -SAREF Smart Applications REFerence ontology - -TCP Transport Control Protocol - -TLS Transport Layer Security - -TS Technical Specification - -UCA Unicode Collation Algorithm - -UL Ultra Light - -UML Unified Modelling Language - -URI Uniform Resource Identifier - -URL Universal Resource Locator - -URN Uniform Resource Name - -UTC Coordinated Universal Time - -UTF Unicode (or Universal Coded Character Set) Transformation Format diff --git a/API-md/9-tabcontext-information-management-framework.md b/API-md/9-tabcontext-information-management-framework.md deleted file mode 100644 index 2c392ffc7e45f91a38885313692640984a055c93..0000000000000000000000000000000000000000 --- a/API-md/9-tabcontext-information-management-framework.md +++ /dev/null @@ -1,4581 +0,0 @@ -# 4 Context Information Management Framework {#tabcontext-information-management-framework number="9"} - -## 4.1 Introduction {#tabintroduction number="9.1"} - -The present clause describes the technical design principles behind the context information management framework supported by NGSI-LD. As stated in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms), 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](18-annex-f-informative-conventions-and-syntax-guidelines.md#annex-f-informative-conventions-and-syntax-guidelines) for details. - -## 4.2 NGSI-LD Information Model {#tabngsi-ld-information-model number="9.2"} - -### 4.2.1 Introduction {#tabintroduction-1 number="9.2.1"} - -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](9-tabcontext-information-management-framework.md#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]](7-tabreferences.md#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]](7-tabreferences.md#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]](7-tabreferences.md#i.8), with classes defining extra concepts such as mobile vs. stationary entities, instantaneous vs. static properties, etc. - -::: FL -![](./media/image2.png){style="width:3.75851in;height:3.04623in"} -::: - -::: {#Figure_4.2.1-1 .TF} -Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure -::: - -### 4.2.2 NGSI-LD Meta Model {#tabngsi-ld-meta-model number="9.2.2"} - -[Figure 4.2.2‑1](9-tabcontext-information-management-framework.md#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. - -::: FL -![](./media/image3.png){style="width:6.69375in;height:1.65625in"} -::: - -::: NF -Legend: -::: - -::: NF -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {NF} | {NF} | -| | | -| [![](./media/image4.png){style="width:0.66695in;height:0.352in"}]{style="position: relative; display: inline-flex;"} | [With capital initial]. Used to refer to a class that is a subclass of Entity or Value. | -+===============================================================================================================================================================================================================================================+======================================================================================================================================================================================================================================================================+ -| [![](./media/image5.png){style="width:0.69in;height:0.44in"}]{style="position: relative; display: inline-flex;"} | [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. | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image6.png){style="width:0.448in;height:0.37334in"}]{style="position: relative; display: inline-flex;"} and [![](./media/image7.png){style="width:0.51648in;height:0.376in"}]{style="position: relative; display: inline-flex;"} | [With small initial]. Used to refer to a proper (direct) class of properties or relationships. | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image8.png){style="width:0.63736in;height:0.35in"}]{style="position: relative; display: inline-flex;"} | [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. | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image9.png){style="width:0.60694in;height:0.37302in"}]{style="position: relative; display: inline-flex;"} | [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.2-1 .TF} -Figure 4.2.2-1: NGSI-LD Core Meta-Model -::: - -Implementations shall support the NGSI-LD Meta-model as follows: - -::: B1plus -- An **NGSI-LD Entity** is a subclass of rdfs:Resource [[1]](7-tabreferences.md#1). -- An **NGSI-LD** **Relationship** is a subclass of rdfs:Resource [[1]](7-tabreferences.md#1). -- An **NGSI-LD** **Property** is a subclass of rdfs:Resource [[1]](7-tabreferences.md#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]](7-tabreferences.md#1). -- An **NGSI-LD Property** shall have a **value,** stated through *hasValue*, which is of type rdf:Property [[1]](7-tabreferences.md#1). An **NGSI-LD Relationship** shall have an **object** stated through *hasObject* which is of type rdf:Property [[1]](7-tabreferences.md#1). -::: - -### 4.2.3 Cross Domain Ontology {#tabcross-domain-ontology number="9.2.3"} - -::: FL -![](./media/image10.png){style="width:6.69375in;height:3.09653in"} -::: - -::: NF -Legend: -::: - -::: NF -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| {NF} | {NF} | -| | | -| [![](./media/image4.png){style="width:0.66695in;height:0.352in"}]{style="position: relative; display: inline-flex;"} | [With capital initial]. Used to refer to a class that is a subclass of Entity or Value. | -+==============================================================================================================================================================================================================================================+======================================================================================================================================================================================================================================================================+ -| [![](./media/image5.png){style="width:0.69in;height:0.44in"}]{style="position: relative; display: inline-flex;"} | [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. | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image6.png){style="width:0.448in;height:0.37334in"}]{style="position: relative; display: inline-flex;"}and [![](./media/image7.png){style="width:0.51648in;height:0.376in"}]{style="position: relative; display: inline-flex;"} | [With small initial]. Used to refer to a proper (direct) class of properties or relationships. | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image8.png){style="width:0.63736in;height:0.35in"}]{style="position: relative; display: inline-flex;"} | [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. | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| [![](./media/image9.png){style="width:0.60694in;height:0.37302in"}]{style="position: relative; display: inline-flex;"} | [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 .TF} -Figure 4.2.3-1: NGSI-LD Core Meta-Model plus the Cross-Domain Ontology -::: - -[Figure 4.2.3‑1](9-tabcontext-information-management-framework.md#Figure_4.2.3-1) describes the concepts introduced by the NGSI-LD Cross-Domain Ontology, which shall be supported by implementations as follows: - -::: B1plus -- **Geo Properties:** Are intended to convey geospatial information and implementations shall support them as defined in [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties). -- **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](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- **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](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). -- **"scope" Property:** Is a Property that enables putting Entities into a hierarchical structure. Implementations shall support it as defined in [clause 4.18](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes). -- **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]](7-tabreferences.md#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](9-tabcontext-information-management-framework.md#tabgeospatial-properties). -- **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](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values). -::: - -[Clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) 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 {#tabngsi-ld-domain-specific-models-and-instantiation number="9.2.4"} - -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](9-tabcontext-information-management-framework.md#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](9-tabcontext-information-management-framework.md#Figure_4.2.4-1) shows the types ["]{.HTML_Code}[Car]{.HTML_Code}["]{.HTML_Code}, ["]{.HTML_Code}[Parking]{.HTML_Code}["]{.HTML_Code}, ["]{.HTML_Code}[Street]{.HTML_Code}["]{.HTML_Code}, ["]{.HTML_Code}[Gate]{.HTML_Code}["]{.HTML_Code}. Entity types can have further subtypes, e.g. ["]{.HTML_Code}[OffStreetParking]{.HTML_Code}["]{.HTML_Code} as subtype of ["]{.HTML_Code}[Parking]{.HTML_Code}["]{.HTML_Code}. - -::: FL -![](./media/image11.png){style="width:6.69375in;height:4.08264in"} -::: - -::: {#Figure_4.2.4-1 .TF} -Figure 4.2.4-1: Cross-Domain Ontology and instantiation -::: - -In addition, two different NGSI-LD Properties are introduced (*hasState*, *reliability*). - -The *adjacentTo* Relationship links entities of type ["]{.HTML_Code}[Parking]{.HTML_Code}["]{.HTML_Code} with entities of type ["]{.HTML_Code}[Street]{.HTML_Code}["]{.HTML_Code}. - -### 4.2.5 UML representation {#tabuml-representation number="9.2.5"} - -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]](7-tabreferences.md#1) to understand the NGSI-LD Information Model. - -In [Figure 4.2.5‑1](9-tabcontext-information-management-framework.md#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. - -::: FL -![](./media/image12.png){style="width:6.69375in;height:3.875in"} -::: - -::: {#Figure_4.2.5-1 .TF} -Figure 4.2.5-1: NGSI-LD information model as UML -::: - -## 4.3 NGSI-LD Architectural Considerations {#tabngsi-ld-architectural-considerations number="9.3"} - -### 4.3.1 Introduction {#tabintroduction-2 number="9.3.1"} - -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. - -::: ondemand_PAR_space_after_12 -The NGSI-LD API implicitly defines two sets of Entities: -::: - -::: B1plus -- the "current state"; -- the "temporal evolution" (both the past and possibly future predictions). -::: - -The NGSI-LD API is structured into a [Core API]{.HTML_Keyboard} and an optional [Temporal API]{.HTML_Keyboard}. The [Core API]{.HTML_Keyboard} manages the current state of Entities. The [Temporal API]{.HTML_Keyboard} is optional and manages the [Temporal Evolution of Entities]{.HTML_Keyboard}. Brokers that intend to implement the [Temporal API]{.HTML_Keyboard} should consider updating the [Temporal Evolution of an Entity]{.HTML_Keyboard} whenever the "current state" is modified via the [Core API]{.HTML_Keyboard}. - -### 4.3.2 Centralized architecture {#tabcentralized-architecture number="9.3.2"} - -[Figure 4.3.2‑1](9-tabcontext-information-management-framework.md#Figure_4.3.2-1) shows a centralized architecture. In the centre is a [Central Broker]{.HTML_Keyboard} that stores all the context information. There are [Context Producers]{.HTML_Keyboard} that use update operations to update the context information in the [Central Broker]{.HTML_Keyboard} and there are [Context Consumers]{.HTML_Keyboard} that request context information from the [Central Broker]{.HTML_Keyboard}, either using synchronous one-time query or asynchronous subscribe/notify operations. The [Central Broker]{.HTML_Keyboard} answers all requests from its storage. [Figure 4.3.2‑1](9-tabcontext-information-management-framework.md#Figure_4.3.2-1) shows one component that acts as both [Context Producer]{.HTML_Keyboard} and [Context Consumer]{.HTML_Keyboard}. The general assumption is that components can have multiple roles, so such components are not explicitly shown in clauses [4.3.3](9-tabcontext-information-management-framework.md#tabdistributed-architecture) and [4.3.4](9-tabcontext-information-management-framework.md#tabfederated-architecture). - -::: FL -[![](./media/image13.png){style="width:4.31475in;height:3.37333in"}]{style="position: relative; display: inline-flex;"} -::: - -::: {#Figure_4.3.2-1 .TF} -Figure 4.3.2-1: Centralized architecture -::: - -### 4.3.3 Distributed architecture {#tabdistributed-architecture number="9.3.3"} - -[Figure 4.3.3‑1](9-tabcontext-information-management-framework.md#Figure_4.3.3-1) shows a distributed architecture. The underlying idea here is that all information is stored by the [Context Sources]{.HTML_Keyboard}. [Context Sources]{.HTML_Keyboard} implement the query and subscription part of the NGSI-LD API as a [Context Broker]{.HTML_Keyboard} does. They register themselves with the [Context Registry]{.HTML_Keyboard}, providing information about what context information they can provide, but not the context information itself, e.g. a certain [Context Source]{.HTML_Keyboard} 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. - -::: FL -[![](./media/image14.png){style="width:4.64567in;height:3.3638in"}]{style="position: relative; display: inline-flex;"} -::: - -::: {#Figure_4.3.3-1 .TF} -Figure 4.3.3-1: Distributed architecture -::: - -[Context Consumers]{.HTML_Keyboard} can query or subscribe to the [Distribution Broker]{.HTML_Keyboard}. On each request, the [Distribution Broker]{.HTML_Keyboard} discovers or does a discovery subscription to the [Context Registry]{.HTML_Keyboard} for relevant [Context Sources]{.HTML_Keyboard}, i.e. those that may provide context information relevant to the respective request from the [Context Consumer]{.HTML_Keyboard}. The [Distribution Broker]{.HTML_Keyboard} then queries or subscribes to each relevant [Context Source]{.HTML_Keyboard}, if possible it aggregates the context information retrieved from the [Context Sources]{.HTML_Keyboard} and provides them to the [Context Consumer]{.HTML_Keyboard}*.* In this mode of operation, it is not visible to the [Context Consumer]{.HTML_Keyboard}, whether the [Context Broker]{.HTML_Keyboard} is a [Central Broker]{.HTML_Keyboard} or a [Distribution Broker]{.HTML_Keyboard}*.* Alternatively, the architecture allows that [Context Consumers]{.HTML_Keyboard} can discover [Context Sources]{.HTML_Keyboard} through the [Context Registry]{.HTML_Keyboard} themselves and then directly request from [Context Sources]{.HTML_Keyboard}. This is shown in [Figure 4.3.3‑1](9-tabcontext-information-management-framework.md#Figure_4.3.3-1) with the fine dashed arrows. - -### 4.3.4 Federated architecture {#tabfederated-architecture number="9.3.4"} - -The federated architecture shown in [Figure 4.3.4‑1](9-tabcontext-information-management-framework.md#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]{.HTML_Keyboard}-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](9-tabcontext-information-management-framework.md#tabdistributed-architecture), except that instead of simple [Context Sources]{.HTML_Keyboard}, whole domains are registered with the respective [Context Broker]{.HTML_Keyboard} as point of access. Typically, the domains will be registered to the federation [Context Registry]{.HTML_Keyboard} 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]{.HTML_Keyboard} discovers the domain [Context Brokers]{.HTML_Keyboard} that can provide relevant information, forwards the request to these [Context Brokers]{.HTML_Keyboard} and aggregates the results, so the application gets the result in the same way as in the centralized and distributed cases. - -::: FL -[![](./media/image15.png){style="width:6.41732in;height:3.40535in"}]{style="position: relative; display: inline-flex;"} -::: - -::: {#Figure_4.3.4-1 .TF} -Figure 4.3.4-1: Federated architecture -::: - -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]{.HTML_Keyboard} and directly contact the [Context Brokers]{.HTML_Keyboard} in the individual domains. - -### 4.3.5 NGSI-LD API Structure and Implementation Options {#tabngsi-ld-api-structure-and-implementation-options number="9.3.5"} - -As stated in [clause 4.3.1](9-tabcontext-information-management-framework.md#tabintroduction-2), the NGSI-LD API is structured into a [Core API]{.HTML_Keyboard} and an optional [Temporal API]{.HTML_Keyboard}. To support the distributed and federated architectures described in clauses [4.3.3](9-tabcontext-information-management-framework.md#tabdistributed-architecture) and [4.3.4](9-tabcontext-information-management-framework.md#tabfederated-architecture) respectively, distributed versions of the operations are needed. They are listed separately under Distributed API and require the operations of the Registry API. The [Registry API]{.HTML_Keyboard} consists of the operations to be implemented by the [Context Registry]{.HTML_Keyboard}. Furthermore, the [JSONLDContext API]{.HTML_Keyboard} 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](10-tabapi-operation-definition.md#tabapi-operation-definition). [Table 4.3.5‑1](9-tabcontext-information-management-framework.md#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. The distributed versions of the operations are separately shown in [Table 4.3.5‑1](9-tabcontext-information-management-framework.md#Table_4.3.5-1) under Distributed API, but there is a single clause for each of the operations describing both the centralized and distributed behaviour. In addition, the Distributed API has support operations only needed in distributed and federated architectures. - -::: {#Table_4.3.5-1 .TH} -Table 4.3.5-1: NGSI-LD API structure -::: - -::: TAL -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| API | Functionality | Operations | -+:======================================================+:============================================================================================================================================================================================================+=====================================================================================================================================================+ -| {TAC} | {TAC} | 5.6.1 Create Entity | -| | | | -| Core API | Context Information Provision - operations for providing or managing Entities and Attributes | 5.6.2 Update Attributes | -| | | | -| | | 5.6.3 Append Attributes | -| | | | -| | | 5.6.4 Partial Attribute Update | -| | | | -| | | 5.6.5 Delete Attribute | -| | | | -| | | 5.6.6 Delete Entity | -| | | | -| | | 5.6.7 Batch Entity Creation | -| | | | -| | | 5.6.8 Batch Entity Upsert | -| | | | -| | | 5.6.9 Batch Entity Update | -| | | | -| | | 5.6.10 Batch Entity Delete | -| | | | -| | | 5.6.17 Merge Entity | -| | | | -| | | 5.6.18 Replace Entity | -| | | | -| | | 5.6.19 Replace Attribute | -| | | | -| | | 5.6.20 Batch Entity Merge | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system]{.ondemand_CHAR_name_Arial_size_9} | 5.7.1 Retrieve Entity | -| | | | -| | | 5.7.2 Query Entities | -| | | | -| | | 5.7.5 Retrieve Available Entity Types | -| | | | -| | | 5.7.6 Retrieve Details of Available Entity Types | -| | | | -| | | 5.7.7 Retrieve Available Entity Type Information | -| | | | -| | | 5.7.8 Retrieve Available Attributes | -| | | | -| | | 5.7.9 Retrieve Details of Available Attributes | -| | | | -| | | 5.7.10 Retrieve Available Attribute Information | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions]{.ondemand_CHAR_name_Arial_size_9} | 5.8.1 Create Subscription | -| | | | -| | | 5.8.2 Update Subscription | -| | | | -| | | 5.8.3 Retrieve Subscription | -| | | | -| | | 5.8.4 Query Subscription | -| | | | -| | | 5.8.5 Delete Subscription | -| | | | -| | | 5.8.6 Notification | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAC} | [Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entitiesand Attributes]{.ondemand_CHAR_name_Arial_size_9} | 5.6.11 Upsert Temporal Evolution of an Entity | -| | | | -| Temporal API | | 5.6.12 Add Attributes to Temporal Evolution of an Entity | -| | | | -| | | 5.6.13 Delete Attributes from Temporal Evolution of an Entity | -| | | | -| | | 5.6.14 Partial Update Attribute instance | -| | | | -| | | 5.6.15 Delete Attribute Instance | -| | | | -| | | 5.6.16 Delete Temporal Evolution of an Entity | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities]{.ondemand_CHAR_name_Arial_size_9} | 5.7.3 Retrieve Temporal Evolution of an Entity | -| | | | -| | | 5.7.4 Query Temporal Evolution of Entities | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| [Distributed API]{.ondemand_CHAR_name_Arial_size_9} | [Distributed Context Information Provision -operations for providing or managing Entities and Attributes]{.ondemand_CHAR_name_Arial_size_9} | [5.6.1 Create Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.2 Update Attributes (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.3 Append Attributes (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.4 Partial Attribute Update (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.5 Delete Attribute (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.6 Delete Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.7 Batch Entity Creation (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.8 Batch Entity Upsert (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.9 Batch Entity Update (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.10 Batch Entity Delete (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.17 Merge Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.18 Replace Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.19 Replace Attribute (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.20 Batch Entity Merge (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Distributed Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system]{.ondemand_CHAR_name_Arial_size_9} | [5.7.1 Retrieve Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.2 Query Entities (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.5 Retrieve Available Entity Types (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.6 Retrieve Details of Available Entity Types (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.7 Retrieve Available Entity Type Information (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.8 Retrieve Available Attributes (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.9 Retrieve Details of Available Attributes (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.10 Retrieve Available Attribute Information (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Distributed Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions]{.ondemand_CHAR_name_Arial_size_9} | [5.8.1 Create Subscription (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.8.2 Update Subscription (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.8.3 Retrieve Subscription (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.8.4 Query Subscription (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.8.5 Delete Subscription (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.8.6 Notification (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Distributed Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entities and Attributes]{.ondemand_CHAR_name_Arial_size_9} | [5.6.11 Upsert Temporal Evolution of an Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.12 Add Attributes to Temporal Evolution of an ]{.ondemand_CHAR_name_Arial_size_9}[ Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.13 Delete Attributes from Temporal]{.ondemand_CHAR_name_Arial_size_9}[ Evolution of an Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.14 Partial Update Attribute instance (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.15 Delete Attribute Instance (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.6.16 Delete Temporal Evolution of an Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Distributed Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities]{.ondemand_CHAR_name_Arial_size_9} | [5.7.3 Retrieve Temporal Evolution of an Entity (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.7.4 Query Temporal Evolution of Entities (distributed)]{.ondemand_CHAR_name_Arial_size_9} | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Support operations for distributed operations]{.ondemand_CHAR_name_Arial_size_9} | [5.14.1 Retrieve EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.2 Update EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.3 Delete EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.4 Create EntityMap for Query Entities]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.5 Create EntityMap for Query Temporal Evolution of Entities]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.15.1 Retrieve Context Source Identity Information]{.ondemand_CHAR_name_Arial_size_9} | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| {TAC} | [Context Source Registration- operations for registering Context Sourcesand managing Context Source Registrations(CSRs)]{.ondemand_CHAR_name_Arial_size_9} | 5.9.2 Register Context Source | -| | | | -| Registry API | | 5.9.3 Update CSR | -| | | | -| | | 5.9.4 Delete CSR | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Context SourceDiscovery - operations for retrieving and discovering CSRs]{.ondemand_CHAR_name_Arial_size_9} | 5.7.1 Retrieve CSR | -| | | | -| | | 5.7.2 Query CSRs | -| +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| | [Context Source RegistrationSubscription - operations for subscribing to CSRs, receiving notifications and managing CSRs]{.ondemand_CHAR_name_Arial_size_9} | 5.11.2 Create CSR Subscription | -| | | | -| | | 5.11.3 Update CSR Subscription | -| | | | -| | | 5.11.4 Retrieve CSR Subscription | -| | | | -| | | 5.11.5 Query CSR Subscription | -| | | | -| | | 5.11.6 Delete CSR Subscription | -| | | | -| | | 5.11.7 CSR Notification | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| [Snapshot API]{.ondemand_CHAR_name_Arial_size_9} | [Operations for creating and managing Snapshots.]{.ondemand_CHAR_name_Arial_size_9} | [5.16.1 Create Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.2 Clone Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.3 Retrieve Snapshot Status]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.4 Update Snapshot Status]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.5 Delete Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | 5.16.6 Snapshot Status Notification | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| [JSONLDContext API]{.ondemand_CHAR_name_Arial_size_9} | [Storing, managing and serving ]{.ondemand_CHAR_name_Arial_size_9}*\@contexts* | 5.13.2 Add *\@context* | -| | | | -| | | 5.13.3 List *\@contexts* | -| | | | -| | | 5.13.4 Serve *\@context* | -| | | | -| | | 5.13.5 Delete and Reload *\@context* | -+-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -All [Context Brokers]{.HTML_Keyboard} shall implement the [Core API]{.HTML_Keyboard}. Context Brokers supporting distributed and federated deployments shall also implement the Distributed API. [Temporal API]{.HTML_Keyboard} and [Registry API]{.HTML_Keyboard} can be implemented by a Broker or by a separate temporal component and [Context Registry]{.HTML_Keyboard} respectively. [Table 4.3.5‑2](9-tabcontext-information-management-framework.md#Table_4.3.5-2) shows the possible implementation configurations. A temporal component implementing the [Temporal API]{.HTML_Keyboard} can also be used completely independently of a [Context Broker]{.HTML_Keyboard}. The [Snapshot API]{.HTML_Keyboard} and the [JSONLD]{.HTML_Keyboard}[Context API]{.HTML_Keyboard} are optional. The managing and serving of *\@contexts* can also be handled by an independent, stand-alone component. - -::: {#Table_4.3.5-2 .TH} -Table 4.3.5-2: Main implementation configurations -::: - -::: TAL -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Description | Temporal API | RegistryAPI | -+====================================================================================================================================+=======================+=======================+ -| Central Broker without temporal support | none | none | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Central Broker with integrated temporal component | local | none | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Central Broker with separate temporal component | separate | none | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments without temporal support and with integrated Context Registry | none | local | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments with integrated temporal component and integrated Context Registry | local | local | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments with separate temporal component and integrated Context Registry | separate | local | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments without temporal support and separate Context Registry | none | separate | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments with integrated temporal component and separate Context Registry | local | separate | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -| Context Broker supporting distributed and federated deployments with separate temporal component and separate Context Registry | separate | separate | -+------------------------------------------------------------------------------------------------------------------------------------+-----------------------+-----------------------+ -::: - -[Table 4.3.5‑3](9-tabcontext-information-management-framework.md#Table_4.3.5-3) shows which operations are implemented and used by the other architectural roles as introduced in [clause 4.3.2](9-tabcontext-information-management-framework.md#tabcentralized-architecture), [clause 4.3.3](9-tabcontext-information-management-framework.md#tabdistributed-architecture) and [clause 4.3.4](9-tabcontext-information-management-framework.md#tabfederated-architecture). In addition, there are separate roles for the Temporal API, i.e. Temporal [Context Producer]{.HTML_Keyboard}, Temporal [Context Source]{.HTML_Keyboard} and Temporal [Context Consumer]{.HTML_Keyboard}. 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 ]{.HTML_Keyboard}[Broker]{.HTML_Keyboard} can implement all roles at the same time. [Context Consumers]{.HTML_Keyboard} typically only interact with [Context ]{.HTML_Keyboard}[Brokers]{.HTML_Keyboard}, but in alternative setups, as shown in [Figure 4.3.3‑1](9-tabcontext-information-management-framework.md#Figure_4.3.3-1), they can also directly interact with the [Context Registry]{.HTML_Keyboard} and then directly contact [Context Sources]{.HTML_Keyboard}. - -::: {#Table_4.3.5-3 .TH} -Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles -::: - -::: TAL -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| NGSI-LD Role | Implements | Uses | -+=============================+=====================================================================================================================+======================================================================================================+ -| Context Consumer | 5.8.6 Notification *-* **if supporting asynchronous interactions** | 5.7.1 Retrieve Entity | -| | | | -| | In case of direct interactions with Context Registry: | 5.7.2 Query Entities | -| | | | -| | 5.11.7 CSR Notification -**if supporting asynchronous interactions** | 5.7.5 Retrieve Available Entity Types | -| | | | -| | | 5.7.6 Retrieve Details of Available Entity Types | -| | | | -| | | 5.7.7 Retrieve Available Entity Type Information | -| | | | -| | | 5.7.8 Retrieve Available Attributes | -| | | | -| | | 5.7.9 Retrieve Details of Available Attributes | -| | | | -| | | 5.7.10 Retrieve Available Attribute Information | -| | | | -| | | 5.8.1 Create Subscription | -| | | | -| | | 5.8.2 Update Subscription | -| | | | -| | | 5.8.3 Retrieve Subscription | -| | | | -| | | 5.8.4 Query Subscription | -| | | | -| | | 5.8.5 Delete Subscription | -| | | | -| | | [5.14.1 Retrieve EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.2 Update EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.3 Delete EntityMap]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.4 Create EntityMap for Query Entities]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.14.5 Create EntityMap for Query Temporal Evolution of Entities]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.15.1 Retrieve Context Source Identity Information]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.1 Create Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.2 Clone Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.3 Retrieve Snapshot Status]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.4 Update Snapshot Status]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.5 Delete Snapshot]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | [5.16.6 Snapshot Status Notification]{.ondemand_CHAR_name_Arial_size_9} | -| | | | -| | | I**n case of direct interactions with Context Registry:** | -| | | | -| | | 5.7.1 Retrieve CSR | -| | | | -| | | 5.7.2 Query CSRs | -| | | | -| | | **if supporting asynchronous interactions:** | -| | | | -| | | 5.11.2 Create CSR Subscription | -| | | | -| | | 5.11.3 Update CSR Subscription | -| | | | -| | | 5.11.4 Retrieve CSR Subscription | -| | | | -| | | 5.11.5 Query CSR Subscription | -| | | | -| | | 5.11.6 Delete CSR Subscription | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Context Producer | none | 5.6.1 Create Entity | -| | | | -| | | 5.6.2 Update Attributes | -| | | | -| | | 5.6.3 Append Attributes | -| | | | -| | | 5.6.4 Partial Attribute Update | -| | | | -| | | 5.6.5 Delete Attribute | -| | | | -| | | 5.6.6 Delete Entity | -| | | | -| | | 5.6.7 Batch Entity Creation | -| | | | -| | | 5.6.8 Batch Entity Upsert | -| | | | -| | | 5.6.9 Batch Entity Update | -| | | | -| | | 5.6.10 Batch Entity Delete | -| | | | -| | | 5.6.17 Merge Entity | -| | | | -| | | 5.6.18 Replace Entity | -| | | | -| | | 5.6.19 Replace Attribute | -| | | | -| | | 5.6.20 Batch Entity Merge | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Context Source | 5.7.1 Retrieve Entity | 5.8.6 Notification | -| | | | -| | 5.7.2 Query Entities | 5.9.2 Register Context Source | -| | | | -| | 5.7.5 Retrieve Available Entity Types | 5.9.3 Update CSR | -| | | | -| | 5.7.6 Retrieve Details of Available Entity Types | 5.9.4 Delete CSR | -| | | | -| | 5.7.7 Retrieve Available Entity Type Information | | -| | | | -| | 5.7.8 Retrieve Available Attributes | | -| | | | -| | 5.7.9 Retrieve Details of Available Attributes | | -| | | | -| | 5.7.10 Retrieve Available Attribute Information | | -| | | | -| | 5.8.1 Create Subscription | | -| | | | -| | 5.8.2 Update Subscription | | -| | | | -| | 5.8.3 Retrieve Subscription | | -| | | | -| | 5.8.4 Query Subscription | | -| | | | -| | 5.8.5 Delete Subscription | | -| | | | -| | [5.14.1 Retrieve EntityMap]{.ondemand_CHAR_name_Arial_size_9} | | -| | | | -| | [5.14.2 Update EntityMap]{.ondemand_CHAR_name_Arial_size_9} | | -| | | | -| | [5.14.3 Delete EntityMap]{.ondemand_CHAR_name_Arial_size_9} | | -| | | | -| | [5.14.4 Create EntityMap for Query Entities]{.ondemand_CHAR_name_Arial_size_9} | | -| | | | -| | 5.14.5 Create EntityMap for Query Temporal Evolution of Entities5.15.1 Retrieve Context Source Identity Information | | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Context Repository | 5.6.1 Create Entity | none | -| | | | -| | 5.6.2 Update Attributes | | -| | | | -| | 5.6.3 Append Attributes | | -| | | | -| | 5.6.4 Partial Attribute Update | | -| | | | -| | 5.6.5 Delete Attribute | | -| | | | -| | 5.6.6 Delete Entity | | -| | | | -| | 5.6.7 Batch Entity Creation | | -| | | | -| | 5.6.8 Batch Entity Upsert | | -| | | | -| | 5.6.9 Batch Entity Update | | -| | | | -| | 5.6.10 Batch Entity Delete | | -| | | | -| | 5.6.17 Merge Entity | | -| | | | -| | 5.6.18 Replace Entity | | -| | | | -| | 5.6.19 Replace Attribute | | -| | | | -| | 5.6.20 Batch Entity Merge | | -| | | | -| | 5.16.1 Create Snapshot | | -| | | | -| | 5.16.2 Clone Snapshot | | -| | | | -| | 5.16.3 Retrieve Snapshot Status | | -| | | | -| | 5.16.4 Update Snapshot Status | | -| | | | -| | 5.16.5 Delete Snapshot | | -| | | | -| | 5.16.6 Snapshot Status Notification | | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Temporal Context Consumer | **In case of direct interactions with Context Registry:** | 5.7.3 Retrieve Temporal Evolution of an Entity | -| | | | -| | 5.11.7 CSR Notification - **if supporting asynchronous interactions** | 5.7.4 Query Temporal Evolution of Entities | -| | | | -| | | **In case of direct interactions with Context Registry:** | -| | | | -| | | 5.7.1 Retrieve CSR | -| | | | -| | | 5.7.2 Query CSRs | -| | | | -| | | **if supporting asynchronous interactions**: | -| | | | -| | | 5.11.2 Create CSR Subscription | -| | | | -| | | 5.11.3 Update CSR Subscription | -| | | | -| | | 5.11.4 Retrieve CSR Subscription | -| | | | -| | | 5.11.5 Query CSR Subscription | -| | | | -| | | 5.11.6 Delete CSR Subscription | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Temporal Context Producer | None | 5.6.11 Upsert Temporal Evolution of an Entity | -| | | | -| | | 5.6.12 Add Attributes to Temporal Evolution of an Entity | -| | | | -| | | 5.6.13 Delete Attributes from Temporal Evolution of an Entity | -| | | | -| | | 5.6.14 Partial Update Attribute instance | -| | | | -| | | 5.6.15 Delete Attribute Instance | -| | | | -| | | 5.6.16 Delete Temporal Evolution of an Entity | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Temporal Context Source | 5.7.3 Retrieve Temporal Evolution of an Entity | 5.9.2 Register Context Source | -| | | | -| | 5.7.4 Query Temporal Evolution of Entities | 5.9.3 Update CSR | -| | | | -| | | 5.9.4 Delete CSR | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Temporal Context Repository | 5.6.11 Upsert Temporal Evolution of an Entity | none | -| | | | -| | 5.6.12 Add Attributes to Temporal Evolution of an Entity | | -| | | | -| | 5.6.13 Delete Attributes from Temporal Evolution of an Entity | | -| | | | -| | 5.6.14 Partial Update Attribute instance | | -| | | | -| | 5.6.15 Delete Attribute Instance | | -| | | | -| | 5.6.16 Delete Temporal Evolution of an Entity | | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -| Context Registry | 5.9.2 Register Context Source | 5.11.7 CSR Notification | -| | | | -| | 5.9.3 Update CSR | | -| | | | -| | 5.9.4 Delete CSR | | -| | | | -| | 5.7.1 Retrieve CSR | | -| | | | -| | 5.7.2 Query CSRs | | -| | | | -| | 5.11.2 Create CSR Subscription | | -| | | | -| | 5.11.3 Update CSR Subscription | | -| | | | -| | 5.11.4 Retrieve CSR Subscription | | -| | | | -| | 5.11.5 Query CSR Subscription | | -| | | | -| | 5.11.6 Delete CSR Subscription | | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+ -::: - -### 4.3.6 Distributed Operations {#tabdistributed-operations number="9.3.6"} - -#### 4.3.6.1 Introduction {#tabintroduction-3 number="9.3.6.1"} - -One fundamental concept underpinning all of the prototypical architectures described above (clauses [4.3.2](9-tabcontext-information-management-framework.md#tabcentralized-architecture), [4.3.3](9-tabcontext-information-management-framework.md#tabdistributed-architecture) and [4.3.4](9-tabcontext-information-management-framework.md#tabfederated-architecture)) is the idea that Entity data does not need to be centralized within a single [Context Broker]{.HTML_Keyboard}*.* When reading context information, a [Context Broker]{.HTML_Keyboard} can be used as a single point of access to retrieve Entity data found distributed across multiple associated [Context Brokers]{.HTML_Keyboard} each receiving a **context consumption** request. Similarly, when modifying an Entity, a single request to a [Context Broker]{.HTML_Keyboard} may result in the operation being distributed and different parts of that Entity being updated across multiple [Context Brokers]{.HTML_Keyboard} each receiving a **context provision** request. - -As long as there is only a centralized [Context Broker]{.HTML_Keyboard}, i.e. there are no [Context Sources]{.HTML_Keyboard} registered, all NGSI-LD requests, with few exceptions such as Update Attributes (see [clause 5.6.2](10-tabapi-operation-definition.md#tabupdate-attributes)) and the batch operations (see clauses [5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation), [5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert), [5.6.9](10-tabapi-operation-definition.md#tabbatch-entity-update), [5.6.10](10-tabapi-operation-definition.md#tabbatch-entity-delete) and [5.6.20](10-tabapi-operation-definition.md#tabbatch-entity-merge)), 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. - -It is the responsibility of the [Context Broker]{.HTML_Keyboard} to respect the registration parameters when issuing distributed requests. For instance, if a registration states that only Entities of a given type are offered, the distributed request does not contain additional types. Such a strict requirement is justified because [Context Sources]{.HTML_Keyboard} (the receivers of the distributed request) are not in a position to determine whether a request has been triggered by a registration, rendering them unable to ensure that the registration parameters are respected in the first place. This applies for any kind of context data a [Context Broker]{.HTML_Keyboard} can exchange such as Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all constraints specified in the registration shall be respected. - -When a [Context Source]{.HTML_Keyboard} is registered, an operation mode is selected. This defines the basis for distributed operations and also defines whether or not the [Context Broker]{.HTML_Keyboard} is permitted to hold context data about the Entities and Attributes locally itself. - -If two registered [Context Sources]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). - -It is possible to restrict a registered [Context Source]{.HTML_Keyboard} to operate on a specific Entity type or list of Entity types. In order for [Context Broker]{.HTML_Keyboard} hierarchies to support and restrict the distribution of such limited operations, the Entity type selector (see [clause 4.17](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-type-selection-language)) can be added as a filter on forwarded requests even where its presence initially seems redundant. - -Furthermore, registered [Context Sources]{.HTML_Keyboard} may indicate that they are only willing to respond to a limited subset of API operations. [Context Brokers]{.HTML_Keyboard} shall respect this, to avoid unnecessarily sending distributed operation requests which are always guaranteed to fail. For example, a [Context Source]{.HTML_Keyboard} may consistently refuse certain API operations since it does not support them. Alternatively, some [Context Source]{.HTML_Keyboard} endpoints (such as updates) may be protected for use by authorized users only, and not accessible to a [Context Broker]{.HTML_Keyboard} without those rights*.* Limited access is likely to be the case in extended data sharing scenarios, where a registered [Context Source]{.HTML_Keyboard}, and the data held within it, may belong to an external third party. - -For the endpoints served, all registered [Context Sources]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabtemporal-properties)) should be supported by registered [Context Sources]{.HTML_Keyboard}, at a minimum no error shall be returned if they are not available when requested. - -#### 4.3.6.2 Additive Registrations {#tabadditive-registrations number="9.3.6.2"} - -For additive registrations, the [Context Broker]{.HTML_Keyboard} 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]{.HTML_Keyboard} itself, and also distributed on to the registered sources. - -An **inclusive** [Context Source Registration]{.HTML_Keyboard} specifies that the [Context Broker]{.HTML_Keyboard} considers all registered [Context Sources]{.HTML_Keyboard} as equals and will distribute operations to those [Context Sources]{.HTML_Keyboard} even if relevant context data is available directly within the [Context Broker]{.HTML_Keyboard} itself (in which case, all results will be integrated in the final response). Data from every[Context Source]{.HTML_Keyboard} registered by an inclusive [Context Source Registration]{.HTML_Keyboard} is requested with an equal priority. This is the default mode of operation. - -An **auxiliary** [Context Source Registration]{.HTML_Keyboard} never overrides data held directly within a [Context Broker]{.HTML_Keyboard}. Auxiliary distributed operations are limited to context information consumption operations (see [clause 5.7](10-tabapi-operation-definition.md#tabcontext-information-consumption)). Context data from auxiliary context sources is only included if it is supplementary to the context data otherwise available to the [Context Broker]{.HTML_Keyboard}. Auxiliary [Context Source Registrations]{.HTML_Keyboard} are always accepted as there can never be a conflict. - -#### 4.3.6.3 Proxied Registrations {#tabproxied-registrations number="9.3.6.3"} - -For proxied registrations, the [Context Broker]{.HTML_Keyboard} 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]{.HTML_Keyboard} itself. - -An **exclusive** [Context Source Registration]{.HTML_Keyboard} specifies that all of the registered context data is held in a single location external to the [Context Broker]{.HTML_Keyboard}*.* The [Context Broker]{.HTML_Keyboard} itself holds no data locally about the registered Attributes and no overlapping proxied [Context Source Registrations]{.HTML_Keyboard} 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:** - -::: B1plus -- 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]{.HTML_Keyboard} has been created, no further exclusive or redirect [Context Source Registrations]{.HTML_Keyboard} can be created for that same combination of Entity ID and Attributes. - -::: ondemand_PAR_space_after_6 -A **redirect** [Context Source Registration]{.HTML_Keyboard} also specifies that the registered context data is held in a location external to the [Context Broker]{.HTML_Keyboard}. It is possible to register (any combination of): -::: - -::: B1plus -- 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]{.HTML_Keyboard}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]{.HTML_Keyboard}. - -#### 4.3.6.4 Limiting Cascading Distributed Operations {#tablimiting-cascading-distributed-operations number="9.3.6.4"} - -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 ]{.HTML_Keyboard}are in turn reliant on previously encountered [Context Sources]{.HTML_Keyboard} thus causing an infinite loop. Therefore, when processing a distributed operation, a specific field listing all previously encountered [Context Sources ]{.HTML_Keyboard}(e.g. a Via header in the response in case of HTTP binding (IETF RFC 7230 [[27]](7-tabreferences.md#27))) 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](9-tabcontext-information-management-framework.md#tabsupporting-multiple-tenants)) each [Tenant]{.HTML_Keyboard} found within each registered [Context Source]{.HTML_Keyboard} shall be considered separately. - -#### 4.3.6.5 Extra information to provide when contacting Context Source {#tabextra-information-to-provide-when-contacting-context-source number="9.3.6.5"} - -::: ondemand_PAR_space_after_10 -If the optional array (of *KeyValuePair* type, as defined by [clause 5.2.22](10-tabapi-operation-definition.md#tabkeyvaluepair)) *contextSourceInfo* of the CSourceRegistration is present, it contains, whatever extra information the [Context Broker]{.HTML_Keyboard} shall convey when contacting the [Context Source]{.HTML_Keyboard}. This can be information the [Context Broker]{.HTML_Keyboard} needs to successfully communicate with the [Context Source]{.HTML_Keyboard} (e.g. Authorization material), or for the [Context Source]{.HTML_Keyboard} to correctly interpret the received content (e.g. the Link URL to fetch an *\@context*). The method for conveying this information is binding-specific, e.g. using headers in the case of HTTP. -::: - -::: ondemand_PAR_space_after_10 -Instead of providing the actual value, the special value ["urn:ngsi-ld:request"]{.HTML_Code} can be used to indicate that the respective value is to be taken from the request that triggered the given request, if present. -::: - -::: EX -EXAMPLE: - -If the key value pair ["user": "urn:ngsi-ld:request" ]{.HTML_Code} is part of *contextSourceInfo* of the CSourceRegistration, the [Context Broker]{.HTML_Keyboard} checks if ["user"]{.HTML_Code} was conveyed in the triggering request. If this is the case, e.g. ["user": "abcd"]{.HTML_Code} , ["user": "abcd"]{.HTML_Code} is also conveyed when contacting the [Context Source]{.HTML_Keyboard} . -::: - -As [Tenant]{.HTML_Keyboard} information, if applicable, is directly specified in the CSourceRegistration, it shall not be part of *contextSourceInfo*[.]{.HTML_Code} 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*[.]{.HTML_Code} If present, such information shall be ignored. - -#### 4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source {#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source number="9.3.6.6"} - -::: ondemand_PAR_space_after_10 -The following key-values have a specific well-defined meaning when defined as elements within the optional array *contextSourceInfo* of the CSourceRegistration. -::: - -If the key ["accept"]{.HTML_Code} is defined: - -::: B1plus -- the value shall be a MIME type acceptable to the [Context Broker]{.HTML_Keyboard} (one of: ["application/json","application/ld+json")]{.HTML_Code} . -- the response from the distributed endpoint shall be returned in this defined format and if necessary, the [Context Broker]{.HTML_Keyboard} shall be responsible for converting this to the desired content type when aggregating responses to the initial request. -::: - -If the key ["contentType"]{.HTML_Code} is defined: - -::: B1plus -- the value shall be a MIME type acceptable to the [Context Broker]{.HTML_Keyboard} (one of: ["application/json","application/ld+json")]{.HTML_Code} . -- the[Context Broker]{.HTML_Keyboard} shall provide the request and the associated *\@context* as required by the MIME type when distributing the request to the context source endpoint, regardless of how it was provided in the initial request. -::: - -If the key ["jsonldContext" ]{.HTML_Code}is defined: - -::: B1plus -- the value shall correspond to a URL reference as defined by the JSON-LD specification [[2]](7-tabreferences.md#2), section 3.1. -- the [Context Broker]{.HTML_Keyboard} shall apply a compaction operation as defined by the JSON-LD specification [[2]](7-tabreferences.md#2), section 4.1.5 over both payload and query parameters using the JSON-LD Context supplied in the value of the ["jsonldContext"]{.HTML_Code} 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]{.HTML_Keyboard}, the ["Content-Type"]{.HTML_Code} of the forwarded request shall be ["application/json"]{.HTML_Code} and the [Context Broker]{.HTML_Keyboard} shall remove any *\@context* members from the payload prior to distributing the request to the context source endpoint. -::: - -If the key ["ngsildConformance" ]{.HTML_Code}is defined: - -::: B1plus -- The value shall define in the form *major.minor*, for example [1.5]{.HTML_Code}. -- The [Context Broker]{.HTML_Keyboard} shall apply a backwards compatibility operation over the payload (as defined by [clause 4.3.6.8](9-tabcontext-information-management-framework.md#tabbackwards-compatibility-of-context-source-payloads)) prior to distributing the request to the context source endpoint such that the forwarded payload conforms to the specified version of the NGSI-LD specification. -::: - -#### 4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations {#tabquerying-and-retrieving-distributed-entities-as-unitary-operations number="9.3.6.7"} - -[Context Broker]{.HTML_Keyboard} architectures assume that Entity data does not need to be centralized within a single [Context Broker]{.HTML_Keyboard}, however, when querying context information, Entity data retrieval can be considered as a unitary operation, masking the fact that each registered [Context Broker]{.HTML_Keyboard} is receiving a separate distributed **Context Consumption** request. - -To process each **Context Consumption** request efficiently, and to support consistent pagination, it is necessary for the [Context Broker]{.HTML_Keyboard} to initially make a broad request to each registered **Context Source** whose registration is matching the request. - -In the case of a **query Entities operation** [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)) or **query Temporal Evolution of Entities operation** [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)), a list of Entity identifiers is returned and stored together with the registration information in an Entity map. Only the Entities whose identifiers are contained in the Entity map are considered when rendering the result pages. Filtering based on queries, geoqueries, scope queries or attribute filters, as provided in the original query request, is applied to the Entities before adding the Entity to a result page, i.e. identifiers of Entities not matching the filters at the time of checking are removed from the Entity map. - -In the case of a **retrieve Entity operation** [(clause 5.7.1](10-tabapi-operation-definition.md#tabretrieve-entity)) or **retrieve Temporal Evolution of an Entity operation** [(clause 5.7.3](10-tabapi-operation-definition.md#tabretrieve-temporal-evolution-of-an-entity)), an Entity map can be used to make subsequent retrievals of the same Entity more efficient, as the Entity map provides the information about which Context Source(s) store relevant Entity information, and other Context Sources do not have to be considered. - -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 [Table 6.4.3.2‑2](11-tabapi-http-binding.md#Table_6.4.3.2-2)) 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]{.HTML_Keyboard} 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. - -When executing **Context Consumption** or **Subscription** operations, a significant optimization in performance can be achieved if it is known a priori whether individual Entities are themselves distributed among [Context Brokers]{.HTML_Keyboard} and [Context Sources]{.HTML_Keyboard}, or if each [Context Broker]{.HTML_Keyboard} and [Context Source]{.HTML_Keyboard} always stores complete Entities. In the latter case all parameters used for filtering such as queries, geoqueries, scope queries or attribute filters can be forwarded and applied locally, whereas in the former case, the Entity first has to be assembled by the [Context Broker]{.HTML_Keyboard} and only then the filtering can be applied. Since being able to apply filters locally is significantly more efficient, a parameter can indicate that, for the given request, only Entities are to be expected that are stored in their entirety on each [Context Broker]{.HTML_Keyboard} and each [Context Sources,]{.HTML_Keyboard} and there are no Entities that are themselves stored in a distributed fashion. Such Entities are also referred to as split Entities. [Context Broker]{.HTML_Keyboard} implementations should enable configuring a default for this parameter, so deployments where no split Entities are to be expected can filter locally and thus be more efficient. - -In the case of split Entities, EntityMaps initially only store "candidate Entities" as no filters could be applied, because only a part of the Entity was available. In the process of pagination, the filters will be (re-)checked. Any Entity not (or no longer) fulfilling the filter shall be removed from the EntityMap. - -#### 4.3.6.8 Backwards compatibility of Context Source payloads {#tabbackwards-compatibility-of-context-source-payloads number="9.3.6.8"} - -When retrieving Entity data found distributed across multiple associated [Context Brokers]{.HTML_Keyboard} each [Context Source]{.HTML_Keyboard} is sent a **context consumption** request. A [Context Broker]{.HTML_Keyboard} shall assume that every [Context Source]{.HTML_Keyboard} will return valid NGSI-LD Entity data in a format that it understands and it shall reject data that is invalid. However, since the definition of a valid NGSI-LD Entity has broadened with each version of the NGSI-LD specification, it is possible that a registered [Context Source ]{.HTML_Keyboard}could respond with valid NGSI-LD Entity data which does not fit the narrower confines of a previous NGSI-LD specification. - -Therefore, when making a **context consumption** request, a [Context Broker]{.HTML_Keyboard} may wish to indicate that it is only capable of interpreting responses which conform to a specific NGSI-LD specification, in which case the [Context Source ]{.HTML_Keyboard}shall endeavour to amend its payload accordingly. [Table 4.3.6.8‑1](9-tabcontext-information-management-framework.md#Table_4.3.6.8-1) describes a minimal level of support for a NGSI-LD Entity data as specified by each version of the NGSI-LD specification, and the expected fallback behaviour required if a **context consumption** request is made to receive data conformant to an earlier version of the NGSI-LD specification. [Table 4.3.6.8‑2](9-tabcontext-information-management-framework.md#Table_4.3.6.8-2) describes conformance fallbacks for an NGSI-LD Property (and its subclasses) and [Table 4.3.6.8‑2](9-tabcontext-information-management-framework.md#Table_4.3.6.8-2) describes conformance fallbacks for an NGSI-LD Relationship (and its subclasses). - -The version of the NGSI-LD specification requested and the conformant version returned is defined in the form *major.minor*, for example [1.5]{.HTML_Code}. - -::: {#Table_4.3.6.8-1 .TH} -Table 4.3.6.8-1: NGSI-LD Entity data type attribute support -::: - -::: TAL -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| Name | Data Type | Definition | Version | Conformant Data Fallback | -| | | | | | -| | | | Introduced | | -+===============================================================+===============================================================+====================================================================================================================================================================+:=============================================================:+===============================================================+ -| id | String | Valid URI | 1.0 | | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| type | String or String[] (see note 1) | 1.0 | | | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| expiresAt | String | *DateTime* as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes) | 1.9 | Remove attribute from payload | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| location | GeoProperty | Default geospatial Property of an entity. See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 1.0 | | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| observationSpace | GeoProperty | See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 1.0 | | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| operationSpace | GeoProperty | See [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties) | 1.0 | | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| scope | String or String[] | See [clause 4.18](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes) | 1.4 | Remove attribute from payload | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | Property or Property[] (see note 2) | Property as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | 1.0 | | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | GeoProperty or GeoProperty[] (see note 2) | [GeoProperty]{.HTML_Keyboard} as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). | 1.0 | | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | LanguageProperty or LanguageProperty[] (see note 2) | [LanguageProperty]{.HTML_Keyboard} as mandated by [clause 4.5.18](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations). | 1.4 | Reformat attribute as Property | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | JsonProperty or JsonProperty[] (see note 2) | [JsonProperty]{.HTML_Keyboard} as mandated by [clause 4.5.24](9-tabcontext-information-management-framework.md#tabngsi-ld-jsonproperty-representations). | 1.8 | Reformat attribute as Property | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | VocabProperty or VocabProperty[] (see note 2) | [VocabProperty]{.HTML_Keyboard} as mandated by [clause 4.5.20](9-tabcontext-information-management-framework.md#tabngsi-ld-vocabproperty-representations). | 1.8 | Reformat attribute as Property | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | ListProperty or ListProperty[] (see note 1) | [ListProperty]{.HTML_Keyboard} as mandated by [clause 4.5.21](9-tabcontext-information-management-framework.md#tabngsi-ld-listproperty-representations). | 1.8 | Reformat attribute as Property | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | Relationship | Relationship as mandated by [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). | 1.0 | | -| | | | | | -| | or Relationship[] (see note 3) | | | | -| +---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| | ListRelationship or ListRelationship[] (see note 3) | [ListRelationship]{.HTML_Keyboard} as mandated by [clause 4.5.22](9-tabcontext-information-management-framework.md#tabngsi-ld-listrelationship-representations). | 1.8 | Reformat attribute as Relationship | -+---------------------------------------------------------------+---------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ -| ::: TAN | -| NOTE 1: | -| | -| From 1.3 onwards, an Entity *type* can be assigned multiple values. For 1.0 backwards compatibility only return a single element with preference to the first instance. | -| ::: | -| | -| ::: TAN | -| NOTE 2: | -| | -| From 1.3 onwards, multiple instances of a *Property* (or subclass of *Property* ) identified by the same Property name can be separated by *datasetId.* For 1.0 backwards compatibility only return a single element of Property Array with preference to the default instance. | -| ::: | -| | -| ::: TAN | -| NOTE 3: | -| | -| From 1.3 onwards, multiple instances of a *Relationship* (or subclass of *Relationship* ) identified by the same Relationship name can be separated by *datasetId.* From 1.3 onwards. For 1.0 backwards compatibility only return a single element of Relationship Array with preference to the default instance. | -| ::: | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_4.3.6.8-2 .TH} -Table 4.3.6.8-2: NGSI-LD Property data type attribute support -::: - -::: TAL -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| Name | Data Type | Definition | Version Introduced | Conformant Data Fallback | -+=============+============================================================================+:===========================================================================================================================================:+====================+===============================+ -| type | String | 1.0 | | | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| value | Any JSON value as defined by IETF RFC 8259 [[6]](7-tabreferences.md#6) | See NGSI-LD Value definition in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms) | 1.0 | | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| datasetId | String | Valid URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) | 1.3 | Remove attribute from payload | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| expiresAt | String | *DateTime* as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes) | 1.9 | Remove attribute from payload | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| observedAt | String | *DateTime* as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) | 1.3 | Remove attribute from payload | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| unitCode | String | As mandated by [[15]](7-tabreferences.md#15) | 1.3 | Remove attribute from payload | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| valueType | String | [See [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations)]{.HTML_Definition} | 1.9 | Remove attribute from payload | -+-------------+----------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -::: - -::: {#Table_4.3.6.8-3 .TH} -Table 4.3.6.8-3: NGSI-LD Relationship data type attribute support -::: - -::: TAL -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| Name | Data Type | Definition | Version Introduced | Conformant Data Fallback | -+=============+======================+=============================================================================================================================================+:==================:+===============================+ -| type | String | Valid URI | 1.0 | | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| object | String or String[] | 1.0 | | | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| datasetId | String | Valid URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support) | 1.3 | Remove attribute from payload | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| expiresAt | String | *DateTime* as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes) | 1.9 | Remove attribute from payload | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| objectType | String or String[] | See [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval) | 1.8 | Remove attribute from payload | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -| observedAt | String | *DateTime* as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties) | 1.3 | Remove attribute from payload | -+-------------+----------------------+---------------------------------------------------------------------------------------------------------------------------------------------+--------------------+-------------------------------+ -::: - -When responding to a **context consumption** request to supply data conforming to a specific NGSI-LD specification, [Context Sources]{.HTML_Keyboard} should indicate the version of the specification the returned payload **actually conforms to**. In general, [Context Sources]{.HTML_Keyboard} will not be expected to be flexible enough to supply payloads conformant to all past and future versions of the specification, but the requesting [Context Broker]{.HTML_Keyboard} may use supplied version information when collating data from multiple [Context Sources]{.HTML_Keyboard}. and to validate and amend received payloads. - -### 4.3.7 Snapshots {#tabsnapshots number="9.3.7"} - -Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables "freezing" the result by retrieving all results immediately and persisting them locally. *Context Consumers* can then query and analyse the Snapshot in a much more consistent way. - -This is especially relevant for distributed cases, where information initially was distributed across multiple *Context Brokers* and *Context Sources*. - -Snapshots offer the full functionality of NGSI-LD available locally and can be used as a basis for simulations that enable making predictions or "what-if" analyses, which are often needed for digital twins. - -## 4.4 Core and user NGSI-LD \@context {#tabcore-and-user-ngsi-ld-context number="9.4"} - -NGSI-LD serialization is based on JSON-LD [[2]](7-tabreferences.md#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: - -::: B1plus -- The core terms needed to uniquely represent the key concepts defined by the NGSI-LD Information Model, as mandated by [clause 4.2](9-tabcontext-information-management-framework.md#tabngsi-ld-information-model). -- The terms needed to uniquely represent all the members that define the API-related Data Types, as mandated by clauses [5.2](10-tabapi-operation-definition.md#tabdata-types) and [5.3](10-tabapi-operation-definition.md#tabnotification-data-types). -- 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"]{.HTML_Code}, which is mapped to *\@id*, and the term ["type"]{.HTML_Code}, which is mapped to *\@type*[.]{.HTML_Code} Since *\@id* and *\@type* are what is typically used in JSON-LD, they may also be used in NGSI-LD requests instead of ["id"]{.HTML_Code} and ["type" ]{.HTML_Code}respectively, wherever this is applicable. In NGSI-LD responses, only ["id"]{.HTML_Code} and ["type"]{.HTML_Code} 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]](7-tabreferences.md#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 and shall contain all the terms as mandated by [annex B](14-annex-b-normative-core-ngsi-ld-context-definition.md#annex-b-normative-core-ngsi-ld-context-definition). - -In addition to the terms defined by the Core NGSI-LD *\@context* (mandatory as per [annex B](14-annex-b-normative-core-ngsi-ld-context-definition.md#annex-b-normative-core-ngsi-ld-context-definition)), a user *\@context* should be provided and it should contain the following terms: - -::: B1plus -- 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: -::: - -::: B2plus -- ["@type"]{.HTML_Code}: . -- ["@id"]{.HTML_Code}: . -::: - -::: B1plus -- One term associated to the name of each *Relationship* mapping the Relationship name with the Relationship Identifier (URI) in the form: -::: - -::: B2plus -- ["@type":"@id"]{.HTML_Code} . -- ["@id"]{.HTML_Code}: . -::: - -Whereas the Core NGSI-LD *\@context* contains JSON-LD Scoped Contexts, the user *\@context* shall not contain JSON-LD Scoped Contexts (see [[2]](7-tabreferences.md#2), ), as described in [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction), because this would enable overwriting terms defined in the Core NGSI-LD *\@context*. - -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](11-tabapi-http-binding.md#tabjson-ld-context-resolution)). - -## 4.5 NGSI-LD Data Representation {#tabngsi-ld-data-representation number="9.5"} - -### 4.5.0 Introduction {#tabintroduction-4 number="9.5.1"} - -All NGSI-LD elements are represented in JSON-LD [[2]](7-tabreferences.md#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](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context), 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]](7-tabreferences.md#16)), the URI ["urn:ngsi-ld:null]{.HTML_Code}["]{.HTML_Code} is used as a replacement for *null* in all places where URI strings are valid JSON values. If an array is required, an array with one single NGSI-LD Null is used. For *languageMap*, the JSON object [{"@none": "urn:ngsi-ld:null"}]{.HTML_Code} is to be used as explained in [clause 4.5.18](9-tabcontext-information-management-framework.md#tabngsi-ld-languageproperty-representations). 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"]{.HTML_Code} is used as a Property *value* or Relationship *object* and the JSON object [{"@none": "urn:ngsi-ld:null"}]{.HTML_Code} for the ["]{.HTML_Code}[languageMap]{.HTML_Code}["]{.HTML_Code} 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}]{.HTML_Code} 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 {#tabngsi-ld-entity-representation number="9.5.2"} - -An NGSI-LD Entity shall be represented by an object encoded using JSON-LD [[2]](7-tabreferences.md#2). The rules described below state the encoding that shall be supported by implementations. [Annex D](16-annex-d-informative-transformation-algorithms.md#annex-d-informative-transformation-algorithms) provides a computational description of this process in terms of an algorithm. - -The JSON-LD object contains the following members: - -**Mandatory** - -::: B1plus -- ["id"]{.HTML_Code} whose value shall be a URI that identifies the Entity. -- ["type]{.HTML_Code}" 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** - -::: B1plus -- ["expiresAt"]{.HTML_Code}: a string as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). -- ["scope"]{.HTML_Code} whose value shall be a Scope as defined in [clause 4.18](9-tabcontext-information-management-framework.md#tabngsi-ld-scopes) or an unordered JSON array with multiple Scopes in case of an Entity that has multiple Scopes. -- ["@context"]{.HTML_Code} a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -- One member for each *Property* as per the rules stated in [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). In case of multiple *Property* instances with the same Property name as described in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support), all instances are provided as an unordered JSON array, and *datasetId* (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)) shall be used to distinguish them. -- One member for each *Relationship* as per the rules stated in [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). In case of multiple *Relationship* instances with the same Relationship name as described in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support), all instances are provided as an unordered JSON array, and *datasetId* (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)) shall be used to distinguish them. -::: - -::: NO -NOTE 1: - -In the following, the term Attribute is used when referring in the text to both a Property and a Relationship (see definition of NGSI-LD Attribute in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms) ). -::: - -::: NO -NOTE 2: - -When GeoJSON representation is selected, the layout of the Entities changes, see [clause 4.5.16](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-entities) for details. -::: - -Terms defined in the Core Context as non-reified Properties (such as ["datasetId"]{.HTML_Code}, ["instanceId"]{.HTML_Code}, etc.) shall not be used as Attribute names. - -Attributes shall not contain any embedded *\@context*, as described in [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). - -### 4.5.2 NGSI-LD Property Representations {#tabngsi-ld-property-representations number="9.5.3"} - -#### 4.5.2.1 Introduction {#tabintroduction-5 number="9.5.3.1"} - -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]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.2.2 Normalized NGSI-LD Property {#tabnormalized-ngsi-ld-property number="9.5.3.2"} - -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](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), which includes the following members: - -**Mandatory** - -- ::: B1plus - ["type"]{.HTML_Code}: the fixed value ["Property"]{.HTML_Code}. - ::: - -- ::: B1plus - ["value"]{.HTML_Code}: the Property Value (see definition of NGSI-LD Value in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)). The datatype URI can be placed in the optional ["valueType"]{.HTML_Code} member. - ::: - - ::: B1plus - An NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["value"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *Property*, as well as in notifications and in temporal evolutions (for encoding a deleted *Property*). - ::: - -::: ondemand_PAR_left_indent_36_space_after_10 -It should be noted that in the JSON-LD serialization, a **number** data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker's internal representation, a **number** is equivalent to either an integer or floating-point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating-point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process. -::: - -**Optional** - -::: B1plus -- ["datasetId"]{.HTML_Code}: a URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- ["expiresAt"]{.HTML_Code}: a string as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). -- ["ngsildproof"]{.HTML_Code}: a Property with the non-reified subproperties ["entityIdSealed"]{.HTML_Code} and ["entityTypeSealed" ]{.HTML_Code}as specified in [[35]](7-tabreferences.md#35). The value of its ["value"]{.HTML_Code} element shall be an object containing the W3C^®^ Data integrity ["proof"]{.HTML_Code} structure [[35]](7-tabreferences.md#35). See [clause C.11](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) for an example. -- ["observedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["unitCode"]{.HTML_Code}: 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]](7-tabreferences.md#15). -- ["valueType"]{.HTML_Code}: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD [\@type]{.HTML_Code} for the Property *value*. When it is a JSON primitive, it should align this with the RDF datatype [[34]](7-tabreferences.md#34). -- 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property)). -- 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship)). -::: - -**System Generated** - -::: B1plus -- ["createdAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["deletedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["instanceId"]{.HTML_Code}: a URI uniquely identifying a Property instance, as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). -- ["modifiedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -::: - -**Output Only** - -::: B1plus -- ["previousValue"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD Property in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entity"]{.HTML_Code}: shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** to define the target Entity of a *Relationship's* object. -- ["entityIdSealed" ]{.HTML_Code}and["entityTypeSealed"]{.HTML_Code}: shall never be present, unless the Property name is ["ngsildproof"]{.HTML_Code}. -- ["entityList"]{.HTML_Code}: shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** to define the target Entities of a *ListRelationship's* object. -- ["json"]{.HTML_Code} and ["previousJson"]{.HTML_Code}: shall never be present, as they define a *JsonProperty* value. -- ["languageMap"]{.HTML_Code} and ["previousLanguageMap"]{.HTML_Code}: shall never be present, as they define a *LanguageProperty* value. -- ["object"]{.HTML_Code} and ["previousObject"]{.HTML_Code}: shall never be present, as they define a *Relationship's* object URI. -- ["objectList"]{.HTML_Code} and ["previousObjectList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Relationship* object URIs. -- ["valueList"]{.HTML_Code} and ["previousValueList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Property* values. -- ["vocab"]{.HTML_Code} and ["previousVocab"]{.HTML_Code}: shall never be present, as they define a *VocabProperty* value. -::: - -#### 4.5.2.3 Concise NGSI-LD Property {#tabconcise-ngsi-ld-property number="9.5.3.3"} - -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](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)). In this case the concise representation is equivalent to simplified representation (see [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation)). If the provided value is a JSON object and contains a ["]{.HTML_Code}[type]{.HTML_Code}["]{.HTML_Code} field, the whole Attribute shall be treated as a normalized representation (see [clause 4.5.2.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property)). - -An NGSI-LD Property which **includes 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](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)) which includes the following members: - -**Mandatory** - -::: B1plus -- ["value"]{.HTML_Code}: the Property Value (see definition of NGSI-LD Value in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)). The datatype URI can be placed in the optional ["valueType"]{.HTML_Code} member. An NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["value"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *Property*, as well as in notifications and in temporal evolutions (for encoding a deleted *Property*). -::: - -::: B1 -It should be noted that in the JSON-LD serialization, a **number** data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker's internal representation, a **number** is equivalent to either an integer or floating-point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating-point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process. -::: - -**Optional** - -::: B1plus -- ["datasetId"]{.HTML_Code}: a URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- ["expiresAt"]{.HTML_Code}: a string as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). -- ["ngsildproof"]{.HTML_Code}: a Property with the non-reified subproperties ["entityIdSealed"]{.HTML_Code} and ["entityTypeSealed" ]{.HTML_Code}as specified in [[35]](7-tabreferences.md#35). The value of its ["value"]{.HTML_Code} element shall be an object containing the W3C^®^Data integrity ["proof"]{.HTML_Code} structure [[35]](7-tabreferences.md#35). See [clause C.11](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) for an example. -- ["observedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["type"]{.HTML_Code}: If missing, ["Property"]{.HTML_Code} can be inferred by the presence of the ["value"]{.HTML_Code} attribute. An exception to this inference rule occurs for geospatial Property Values, where the ["GeoProperty"]{.HTML_Code} sub-type shall be inferred instead, if the Property Value resolves to a supported GeoJSON geometry (see [clause 4.7](9-tabcontext-information-management-framework.md#tabgeospatial-properties)). -- ["unitCode"]{.HTML_Code}: 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]](7-tabreferences.md#15). -- ["valueType"]{.HTML_Code}: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD [\@type]{.HTML_Code} for the Property *value*. When it is a JSON primitive, it should align this with the RDF datatype [[34]](7-tabreferences.md#34). -- 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property)). -- 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship)). -::: - -**System Generated** - -::: B1plus -- ["createdAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["deletedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["instanceId"]{.HTML_Code}: a URI uniquely identifying a Property instance as mandated by [clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property). -- ["modifiedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -::: - -**Output Only** - -::: B1plus -- ["previousValue"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD Property in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entity"]{.HTML_Code}: shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** to define the target Entity of a *Relationship's* object. -- ["entityIdSealed" ]{.HTML_Code}and["entityTypeSealed" ]{.HTML_Code}shall never be present, unless the Property name is ["ngsildproof"]{.HTML_Code}. -- ["entityList"]{.HTML_Code}: shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** to define the target Entities of a *ListRelationship's* object. -- ["languageMap"]{.HTML_Code} and ["previousLanguageMap"]{.HTML_Code}: shall never be present, as they define a *LanguageProperty* value. -- ["json"]{.HTML_Code} and ["previousJson"]{.HTML_Code}: shall never be present, as they define a *JsonProperty* value. -- ["object"]{.HTML_Code} and ["previousObject"]{.HTML_Code}: shall never be present, as they define a *Relationship's* object URI. -- ["objectList"]{.HTML_Code} and ["previousObjectList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Relationship* object URIs. -- ["vocab"]{.HTML_Code} and ["previousVocab"]{.HTML_Code}: shall never be present, as they define a *VocabProperty* value. -- ["valueList"]{.HTML_Code} and ["previousValueList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Property* values. -::: - -### 4.5.3 NGSI-LD Relationship Representations {#tabngsi-ld-relationship-representations number="9.5.4"} - -#### 4.5.3.1 Introduction {#tabintroduction-6 number="9.5.4.1"} - -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]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.3.2 Normalized NGSI-LD Relationship {#tabnormalized-ngsi-ld-relationship number="9.5.4.2"} - -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](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)) with the following terms: - -**Mandatory** - -::: B1plus -- ["object"]{.HTML_Code}: the Relationship's object represented by a URI or array of URIs. An NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["object"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *Relationship*, as well as in notifications and in temporal evolutions (for encoding a deleted *Relationship*). -- ["type"]{.HTML_Code}: the fixed value ["Relationship"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- ["datasetId"]{.HTML_Code}: a URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- ["expiresAt"]{.HTML_Code}: a string as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). -- ["ngsildproof"]{.HTML_Code}: a Property, as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations), with the non-reified subproperties ["entityIdSealed"]{.HTML_Code} and ["entityTypeSealed" ]{.HTML_Code}as specified in [[35]](7-tabreferences.md#35). The value of its ["value"]{.HTML_Code} element shall be an object containing the W3C^®^Data integrity ["proof"]{.HTML_Code} structure [[35]](7-tabreferences.md#35). See [clause C.11](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) for an example. -- ["objectType"]{.HTML_Code}: a string as mandated by [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval). -- ["observedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship)). -- 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property)). -::: - -**System Generated** - -::: B1plus -- ["createdAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["deletedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)*.* -- ["instanceId"]{.HTML_Code}: a URI uniquely identifying a Relationship instance as mandated by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). -- ["modifiedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -::: - -**Output Only** - -::: B1plus -- ["entity"]{.HTML_Code}: only provided in case of [Linked Entity]{.HTML_Keyboard} **retrieval,** and only if the inline *join* option is explicitly requested (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), where it used to define the target [Linked Entity]{.HTML_Keyboard} of a Relationship's object in **normalized** **representation**. -- ["previousObject":]{.HTML_Code} only provided if the *showChanges* option is explicitly requested. It represents the previous Relationship ["object"]{.HTML_Code}, before the triggering change. The representation is the same as that of ["object"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD Relationship in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entityIdSealed" ]{.HTML_Code}and["entityTypeSealed" ]{.HTML_Code}shall never be present. -- ["entityList"]{.HTML_Code} shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** to define the target Entities of a *ListRelationship's* object. -- ["languageMap"]{.HTML_Code} and["previousLanguageMap": ]{.HTML_Code}shall never be present, as they define a *LanguageProperty* value. -- ["json"]{.HTML_Code} and ["previousJson"]{.HTML_Code}: shall never be present, as they define a *JsonProperty* value. -- ["objectList"]{.HTML_Code} and ["previousObjectList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Relationship* object URIs. -- ["unitCode"]{.HTML_Code}: shall never be present, as *Relationships* are unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as they define a *Property* value. -- ["valueList"]{.HTML_Code} and ["previousValueList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Property* values. -- ["vocab"]{.HTML_Code} and ["previousVocab"]{.HTML_Code}: shall never be present, as they define a *VocabProperty* value. -::: - -#### 4.5.3.3 Concise NGSI-LD Relationship {#tabconcise-ngsi-ld-relationship number="9.5.4.3"} - -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](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)) with the following terms: - -**Mandatory** - -::: B1plus -- ["object"]{.HTML_Code}: the Relationship's object represented by a URI or array of URIs. An NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["object"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *Relationship*, as well as in notifications and in temporal evolutions (for encoding a deleted *Relationship*). -::: - -**Optional** - -::: B1plus -- ["datasetId"]{.HTML_Code}: a URI as mandated by [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support). -- ["expiresAt"]{.HTML_Code}: a string as mandated by [clause 4.22](9-tabcontext-information-management-framework.md#tabtransient-storage-of-entities-and-attributes). -- ["ngsildproof"]{.HTML_Code}: a Property, as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations), with the non-reified subproperties ["entityIdSealed"]{.HTML_Code} and ["entityTypeSealed" ]{.HTML_Code}as specified in [[35]](7-tabreferences.md#35). The value of its ["value"]{.HTML_Code} element shall be an object containing the W3C^®^Data integrity ["proof"]{.HTML_Code} structure [[35]](7-tabreferences.md#35). See [clause C.11](15-annex-c-informative-examples-of-using-the-api.md#c.11tabentity-with-digital-signature-for-a-property) for an example. -- ["observedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["objectType"]{.HTML_Code}: a string as mandated by [clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval). -- ["type"]{.HTML_Code}: If missing, ["Relationship"]{.HTML_Code} can be inferred by the presence of the ["object"]{.HTML_Code} 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship)). -- 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property)). -::: - -**System Generated** - -::: B1plus -- ["createdAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["deletedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -- ["instanceId"]{.HTML_Code}: a URI uniquely identifying a Relationship instance as mandated by [clause 4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship). -- ["modifiedAt"]{.HTML_Code}: a string as mandated by [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties). -::: - -**Output Only** - -::: B1plus -- ["entity"]{.HTML_Code}: only provided in case of [Linked Entity]{.HTML_Keyboard} **retrieval**, and only if the inline *join* option is explicitly requested (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), where it used to define the target [Linked Entity]{.HTML_Keyboard} of a Relationship's object in **concise** **representation**. -- ["previousObject"]{.HTML_Code}: only provided if the *showChanges* option is explicitly requested. It represents the previous Relationship ["object"]{.HTML_Code}, before the triggering change. The representation is the same as that of ["object"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD Relationship in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entityIdSealed" ]{.HTML_Code}and["entityTypeSealed" ]{.HTML_Code}shall never be present. -- ["entityList"]{.HTML_Code}: shall never be present, as it is used during inline [Linked Entity]{.HTML_Keyboard} **retrieval** (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)) to define the target Entities of a *ListRelationship*'s object. -- ["languageMap"]{.HTML_Code} and ["previousLanguageMap"]{.HTML_Code}: shall never be present, as they define a *LanguageProperty* value. -- ["json"]{.HTML_Code} and ["previousJson"]{.HTML_Code}: shall never be present, as they define a *JsonProperty* value. -- ["objectList"]{.HTML_Code} and ["previousObjectList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Relationship* object URIs. -- ["unitCode"]{.HTML_Code}: shall never be present, as Relationships are unitless. -- ["valueList"]{.HTML_Code} and ["previousValueList"]{.HTML_Code}: shall never be present, as they define an ordered array of *Property* values. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as they define a *Property* value. -- ["vocab"]{.HTML_Code} and ["previousVocab"]{.HTML_Code}: 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](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)), 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"]{.HTML_Code}*.* - -### 4.5.4 Simplified Representation {#tabsimplified-representation number="9.5.5"} - -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]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -The simplified representation of an Entity shall be a JSON-LD object containing the following members: - -**Mandatory** - -::: B1plus -- ["id"]{.HTML_Code} whose value shall be a URI that identifies the Entity. -- ["type"]{.HTML_Code} 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** - -::: B1plus -- ["@context",]{.HTML_Code} a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -- For each *Property* a member whose key is the Property name (a term) and whose value is the Property Value. -::: - -::: EX -EXAMPLE 1: - -["name": "David Robert Jones"]{.HTML_Sample} -::: - -::: B1plus -- In the multi-attribute case (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), 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"]{.HTML_Code}, 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"]{.HTML_Code}. -::: - -::: EX -EXAMPLE 2: -::: - -["name": {]{.HTML_Sample} - -[  "dataset": {]{.HTML_Sample} - -[    "@none": "David Robert Jones",]{.HTML_Sample} - -[    "urn:ngsi-ld:datasetId:001": "David Bowie",]{.HTML_Sample} - -[    "urn:ngsi-ld:datasetId:002": "Ziggy Stardust"]{.HTML_Sample} - -[  }]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- For each *GeoProperty*, a member whose key is the Property name (a term) and whose value is the Property Value. -::: - -::: EX -EXAMPLE 3: - -["location": {"type": "Point", "coordinates": [13.3986, 52.5547]}]{.HTML_Sample} -::: - -::: B1plus -- 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"]{.HTML_Code} where the value shall correspond to a *LanguageProperty* *languageMap*. -::: - -::: EX -EXAMPLE 4: - -["says": {"languageMap": {"en": "yes", "fr": "oui"}]{.HTML_Sample} -::: - -::: B1plus -- 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"]{.HTML_Code} where the value shall correspond to the raw JSON data that cannot be held in JSON-LD format. Within the example below, the [id]{.HTML_Code} attribute is never expanded to [\@id]{.HTML_Code} and therefore does not have to be defined as a URI, and the [value]{.HTML_Code} attribute is never expanded to [ngsi-ld:hasValue]{.HTML_Code}. -::: - -::: EX -EXAMPLE 5: -::: - -["parkingTickets": {]{.HTML_Sample} - -[  "json": {]{.HTML_Sample} - -[     "id": "85a6cc52-0589-45f9",]{.HTML_Sample} - -[     "value": "Overstay 60 minutes"]{.HTML_Sample} - -[  }]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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"]{.HTML_Code} where the value shall correspond to a *VocabProperty* *vocab*. -::: - -::: EX -EXAMPLE 6: - -["gender": {"vocab": "Male"}]{.HTML_Sample} -::: - -::: B1plus -- 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). -::: - -::: EX -EXAMPLE 7: - -["]{.ondemand_CHAR_color_000000} [providedBy": "urn:ngsi-ld:Device:31415"]{.HTML_Sample} -::: - -::: EX -EXAMPLE 8: -::: - -["devices": []{.HTML_Sample} - -[  "urn:ngsi-ld:Device:14142",]{.HTML_Sample} - -[     "urn:ngsi-ld:Device:13562", ]{.HTML_Sample} - -[     "urn:ngsi-ld:Device:37309"]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the inline [Linked Entity]{.HTML_Keyboard} **retrieval** case (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), 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. -::: - -::: EX -EXAMPLE 9: -::: - -["providedBy": {]{.HTML_Sample} - -["id": "urn:ngsi-ld:Device:31415",]{.HTML_Sample} - -["type": "Device",]{.HTML_Sample} - -["]{.HTML_Sample}[brandName]{.HTML_Sample}[": "]{.HTML_Sample}[Anemometer]{.HTML_Sample}[",]{.HTML_Sample} - -["manufacturerName": "Cyberdyne Systems",]{.HTML_Sample} - -["]{.HTML_Sample}[windSpeed]{.HTML_Sample}[": ]{.HTML_Sample}[60]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: EX -EXAMPLE 10: -::: - -["devices": []{.HTML_Sample} - -[  {]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:14142",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Anemometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Cyberdyne Systems",]{.HTML_Sample} - -[ "windSpeed": 60]{.HTML_Sample} - -[    },]{.HTML_Sample} - -[    {]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:13562",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Hygromometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Acme Corporation",]{.HTML_Sample} - -[       "humidity": 64]{.HTML_Sample} - -[    },]{.HTML_Sample} - -[    { ]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:37309",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Barometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Trask Industries",]{.HTML_Sample} - -[    "pressure": 760]{.HTML_Sample} - -[    }]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the flattened [Linked Entity]{.HTML_Keyboard} **retrieval** case (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)), 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. -::: - -::: EX -EXAMPLE 11: -::: - -[[]{.HTML_Sample} - -[  {]{.HTML_Sample} - -[...]{.HTML_Sample}[etc]{.HTML_Sample} - -["]{.HTML_Sample}[providedBy]{.HTML_Sample}[": "urn:ngsi-ld:Device:31415"]{.HTML_Sample} - -[  },]{.HTML_Sample} - -[{]{.HTML_Sample} - -[ "id": "urn:ngsi-ld:Device:31415",]{.HTML_Sample} - -[ "type": "Device",]{.HTML_Sample} - -[ "brandName": "Anemometer",]{.HTML_Sample} - -[ "manufacturerName": "Cyberdyne Systems",]{.HTML_Sample} - -[ "windSpeed": 60]{.HTML_Sample} - -[}]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: EX -EXAMPLE 12: -::: - -[[]{.HTML_Sample} - -[    {]{.HTML_Sample} - -[      ... etc]{.HTML_Sample} - -[      "providedBy": []{.HTML_Sample} - -[    "urn:ngsi-ld:Device:14142", ]{.HTML_Sample} - -[         "urn:ngsi-ld:Device:13562", ]{.HTML_Sample} - -[         "urn:ngsi-ld:Device:37309"]{.HTML_Sample} - -[       ]]{.HTML_Sample} - -[    },]{.HTML_Sample} - -[    {]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:14142",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Anemometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Cyberdyne Systems",]{.HTML_Sample} - -[       "windSpeed": 60]{.HTML_Sample} - -[    },]{.HTML_Sample} - -[    {]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:13562",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Hygromometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Acme Corporation",]{.HTML_Sample} - -[       "humidity": 64]{.HTML_Sample} - -[    },]{.HTML_Sample} - -[    {]{.HTML_Sample} - -[       "id": "urn:ngsi-ld:Device:37309",]{.HTML_Sample} - -[       "type": "Device",]{.HTML_Sample} - -[       "brand]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Barometer",]{.HTML_Sample} - -[       "manufacturer]{.HTML_Sample}[N]{.HTML_Sample}[ame": "Trask Industries",]{.HTML_Sample} - -[       "pressure": 760]{.HTML_Sample} - -[    }]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the multi-attribute case (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), 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"]{.HTML_Code} 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"]{.HTML_Code}. -::: - -::: EX -EXAMPLE 13: -::: - -["]{.HTML_Sample}[providedBy]{.HTML_Sample}[": {]{.HTML_Sample} - -["dataset": {]{.HTML_Sample} - -[    "@none": "urn:ngsi-ld:]{.HTML_Sample}[Device]{.HTML_Sample}[:31415",]{.HTML_Sample} - -["urn:ngsi-ld:datasetId:001": "urn:ngsi-ld:]{.HTML_Sample}[Device]{.HTML_Sample}[:27182",]{.HTML_Sample} - -["urn:ngsi-ld:datasetId:002": "urn:ngsi-ld:]{.HTML_Sample}[Device]{.HTML_Sample}[:14142"]{.HTML_Sample} - -[}]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- For each *ListProperty* a member whose key is the Property name (a term) and whose value is an ordered array holding the Property Values. -::: - -::: EX -EXAMPLE 14: - -["periods": ["First", "Second", "Third", "Fourth"]]{.HTML_Sample} -::: - -::: B1plus -- In the multi-attribute case (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), 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"]{.HTML_Code} 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 *ListProperty* *valueList*. The default *datasetId* (where present) is represented by the JSON-LD keyword ["@none"]{.HTML_Code}. -::: - -::: EX -EXAMPLE 15: -::: - -["periods": {]{.HTML_Sample} - -["dataset": {]{.HTML_Sample} - -[    "@none": ["First", "Second", "Third", "Fourth"],]{.HTML_Sample} - -[    "urn:ngsi-ld:datasetId:001": ["1st", "2nd", "3rd", "4th"],]{.HTML_Sample} - -[    "urn:ngsi-ld:datasetId:002": ["Primary", "Secondary", "Tertiary", "Quaternary"]]{.HTML_Sample} - -[}]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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). -::: - -::: EX -EXAMPLE 16: -::: - -["route":[]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0101",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0102",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:9912"]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the inline [Linked Entity]{.HTML_Keyboard} **retrieval** case (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), 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. -::: - -::: EX -EXAMPLE 17: -::: - -["route": []{.HTML_Sample} - -[{]{.HTML_Sample} - -["id": "urn:ngsi-ld: BusStop:0101"]{.HTML_Sample}[,]{.HTML_Sample} - -["type": "BusStop",]{.HTML_Sample} - -["stopName": "High Street",]{.HTML_Sample} - -["location": {"type": Point, coordinates [54.112,0.334]}}]{.HTML_Sample} - -[},]{.HTML_Sample} - -[{]{.HTML_Sample} - -["id": "urn:ngsi-ld: BusStop:0102"]{.HTML_Sample}[,]{.HTML_Sample} - -["type": "BusStop",]{.HTML_Sample} - -["stopName": "Station Road", ]{.HTML_Sample} - -["location": {"type": Point, coordinates [54.101,0.302]}}]{.HTML_Sample} - -[},]{.HTML_Sample} - -[{]{.HTML_Sample} - -["id": "urn:ngsi-ld: BusStop:9912"]{.HTML_Sample}[,]{.HTML_Sample} - -["type": "BusStop",]{.HTML_Sample} - -["stopName": "Mornington Cresent", ]{.HTML_Sample} - -["location": {"type": Point, coordinates [54.142,0.332]}]{.HTML_Sample} - -[}]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the flattened [Linked Entity]{.HTML_Keyboard} **retrieval** case (see [clause 4.5.23.3](9-tabcontext-information-management-framework.md#tabflattened-linked-entity-representation)), 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. -::: - -::: EX -EXAMPLE 18: -::: - -[[]{.HTML_Sample} - -[  {]{.HTML_Sample} - -[    ...]{.HTML_Sample}[etc]{.HTML_Sample} - -[    "route": []{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0101",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0102",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:9912"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[  },]{.HTML_Sample} - -[  {]{.HTML_Sample} - -["id": "urn:ngsi-ld: BusStop:0101"]{.HTML_Sample} - -["type": "BusStop",]{.HTML_Sample} - -["stopName": "High Street", ]{.HTML_Sample} - -[    "location: {"type": "Point", "coordinates": [54.112,0.334]}}]{.HTML_Sample} - -[  {]{.HTML_Sample} - -[    "id": "urn:ngsi-ld: BusStop:0102",]{.HTML_Sample} - -[ "type": "BusStop",]{.HTML_Sample} - -["stopName": "Station Road", ]{.HTML_Sample} - -[    "location": {"type": "Point", "coordinates": [54.101,0.302]}}]{.HTML_Sample} - -[  },]{.HTML_Sample} - -[  {]{.HTML_Sample} - -["id": "urn:ngsi-ld:BusStop:9912"]{.HTML_Sample} - -["type": "BusStop",]{.HTML_Sample} - -["stopName": "Mornington Cresent", ]{.HTML_Sample} - -[    "location: {"type": "Point", "coordinates": [54.142,0.332]}]{.HTML_Sample} - -[  }]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -- In the multi-attribute case (see [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support)), 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"]{.HTML_Code} 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 array of objects of the relationship list. The default *datasetId* (where present) is represented by the JSON-LD keyword ["@none"]{.HTML_Code}. -::: - -::: EX -EXAMPLE 19: -::: - -["route": {]{.HTML_Sample} - -["dataset": {]{.HTML_Sample} - -[    "@none": []{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0101",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0102",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:9912"]{.HTML_Sample} - -[],]{.HTML_Sample} - -["urn:ngsi-ld:datasetId:001": ]{.HTML_Sample}[[]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0101",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0102",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0022"]{.HTML_Sample} - -[],]{.HTML_Sample} - -[     "urn:ngsi-ld:datasetId:002": []{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0101",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0102",]{.HTML_Sample} - -["urn:ngsi-ld:BusStop:0022",]{.HTML_Sample} - -["]{.HTML_Sample}[urn:ngsi-ld:BusStop:9912"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[}]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: NO -NOTE: - -When the simplified GeoJSON representation is selected, the layout of the Entities changes, see [clause 4.5.17](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-entities) for details. -::: - -### 4.5.5 Multi-Attribute Support {#tabmulti-attribute-support number="9.5.6"} - -#### 4.5.5.1 Introduction {#tabintroduction-7 number="9.5.6.1"} - -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"]{.HTML_Code} Relationships to all sorts of objects currently in the room that have been put there by different people (a separate ["placedBy]{.HTML_Code}["]{.HTML_Code}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"]{.HTML_Code}. It is introduced for Properties and Relationships in clauses [4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations) and [4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations) 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 ["d]{.HTML_Code}[atasetId]{.HTML_Code}["]{.HTML_Code}[: "@none"]{.HTML_Code} 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](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -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"]{.HTML_Code} 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, expiresAt* and *observedAt*, and also the *unitCode* Property. - -#### 4.5.5.2 Processing of Conflicting Transient Entities {#tabprocessing-of-conflicting-transient-entities number="9.5.6.2"} - -In case of conflicting information when an Entity is received from a registered [Context Source ]{.HTML_Keyboard}and marked with an *expiresAt DateTime,* but this *expiresAt* is not duplicated across all versions of the Entity received across all registered [Context Sources]{.HTML_Keyboard}, the following mechanism shall be used to differentiate. - -For each version of the Entity received where the *expiresAt* non-reified attribute is present at the Entity level: - -::: B1plus -- If no *expiresAt* attribute is present as a property of an Attribute, a non-reified *expiresAt* attribute is added as a property of that Attribute corresponding to the *expiresAt* found on the Entity. -- If the *expiresAt* attribute is present as a property of an Attribute, and the value on the Attribute is further in the future than the *expiresAt* value found on the Entity, the value of the *expiresAt* on the Attribute is overwritten to corresponding to the earlier *DateTime.* -::: - -#### 4.5.5.3 Processing of Conflicting Attributes {#tabprocessing-of-conflicting-attributes number="9.5.6.3"} - -In case of conflicting information for an Attribute, where a *datasetId* is duplicated, but there are differences in the other attribute data, if an *expiresAt DateTime* is present on the Attribute and the date lies in the past, it shall be discarded, thereafter 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. - -When conflicting information is received for the non-reified *expiresAt* attribute at an Entity level: - -::: B1plus -- If an *expiresAt* attribute is missing from at least one version of the Entity received from registered [Context Sources]{.HTML_Keyboard}, the *expiresAt* attribute is removed from the Entity. -- Otherwise, the *expiresAt* attribute of the Entity is set to the *DateTime* corresponding to the *expiresAt* *DateTime* which is furthest in the future. -::: - -### 4.5.6 Temporal Representation of an Entity {#tabtemporal-representation-of-an-entity number="9.5.7"} - -The temporal representation of an Entity is the way to represent the [Temporal Evolution of an Entity]{.HTML_Keyboard}: the Entity shall be as mandated by [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation), but for each Property and Relationship their temporal representation shall be provided as mandated by clauses [4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property) and [4.5.8](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-relationship) and the Scope (if present) shall be represented as a temporal representation of a Property [(clause 4.5.7](9-tabcontext-information-management-framework.md#tabtemporal-representation-of-a-property)) 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]{.HTML_Keyboard}. In case the Temporal Evolution of the Scope is updated as the result of a change from the [Core API]{.HTML_Keyboard}, the *observedAt* sub-Property should be set as a copy of the *modifiedAt* sub-Property. - -### 4.5.7 Temporal Representation of a Property {#tabtemporal-representation-of-a-property number="9.5.8"} - -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 (or a single JSON-LD object in case only one is present), each one representing an instance of the Property (as mandated by [clause 4.5.2](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations)) at a particular point in time, which is recorded as a Temporal Property of the instance (typically *observedAt*). See example in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.6](15-annex-c-informative-examples-of-using-the-api.md#c.5.6tabtemporal-query-simplified-representation). In case the *Property* is deleted, an instance of the *Property* is recorded with its *value* set to the URI ["urn:ngsi-ld:null"]{.HTML_Code} 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 [[i.18]](7-tabreferences.md#i.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 {#tabtemporal-representation-of-a-relationship number="9.5.9"} - -The temporal evolution of a 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 (or a single JSON-LD object in case only one is present), each one representing an instance of the Relationship (as mandated by [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations)) at a particular point in time, which is recorded as a Temporal Property of the instance (typically *observedAt*). See example in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.5](15-annex-c-informative-examples-of-using-the-api.md#c.5.5tabtemporal-query). In case the *Relationship* is deleted, an instance of the *Relationship* is recorded with its *object* set to the URI ["urn:ngsi-ld:null"]{.HTML_Code} 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 [[i.18]](7-tabreferences.md#i.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 {#tabsimplified-temporal-representation-of-an-entity number="9.5.10"} - -The NGSI-LD specification defines an alternative, abbreviated temporal representation of [Temporal Evolution of ]{.HTML_Keyboard}[Entities]{.HTML_Keyboard}, 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]{.HTML_Keyboard} through specific request parameters. An example can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.6](15-annex-c-informative-examples-of-using-the-api.md#c.5.6tabtemporal-query-simplified-representation). - -The simplified temporal representation of an Entity shall be a JSON-LD object containing the following members: - -**Mandatory** - -::: B1plus -- ["id"]{.HTML_Code} whose value shall be a URI that identifies the Entity. -- ["type"]{.HTML_Code} 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** - -::: B1plus -- ["@context"]{.HTML_Code}, a JSON-LD*\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["values"]{.HTML_Code}. The value of the referred ["values"]{.HTML_Code} 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*). -::: - -::: EX -EXAMPLE 1: - -``` json -"name": { -  "type": "Property", -  "values": [ -    [ -      "Joe Bloggs", -      "2022-08-09T18:25:02Z" -    ], -    [ -      "Bill Smith", -      "2022-08-10T18:25:02Z" -    ] -  ] -} -``` -::: - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["values"]{.HTML_Code}. The value of the referred ["values"]{.HTML_Code} 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["languageMaps"]{.HTML_Code}. The value of the referred ["languageMaps"]{.HTML_Code} 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"]{.HTML_Code} where the value shall correspond to a *LanguageProperty* *languageMap* and the second element shall correspond to the associated Temporal Property (for instance *observedAt*). -::: - -::: EX -EXAMPLE 2: -::: - -["says": {]{.HTML_Sample} - -["type": "LanguageProperty",]{.HTML_Sample} - -[  "languageMaps": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[{"languageMap": {"en": "yes", "fr": "oui"}},]{.HTML_Sample} - -["2022-08-09T18:25:02Z"]{.HTML_Sample} - -[],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[{"languageMap": {"en": "no", "fr": "non"}},]{.HTML_Sample} - -["2022-08-10T18:25:02Z"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[]]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["valueLists"]{.HTML_Code}. The value of the referred ["valueLists"]{.HTML_Code} 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*). -::: - -::: EX -EXAMPLE 3: -::: - -["period": {]{.HTML_Sample} - -[  "type": "ListProperty",]{.HTML_Sample} - -[  "valueLists": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["First", "Second", "Third", "Fourth"],]{.HTML_Sample} - -[      "2022-08-09T18:25:02Z"]{.HTML_Sample} - -[    ],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["1st", "2nd", "3rd", "4th"],]{.HTML_Sample} - -[      "2022-08-10T18:25:02Z"]{.HTML_Sample} - -[    ]]{.HTML_Sample} - -[  ]]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["jsons"]{.HTML_Code}. The value of the referred ["jsons"]{.HTML_Code} 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"]{.HTML_Code}, 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*). -::: - -::: EX -EXAMPLE 4: -::: - -["parkingTickets": {]{.HTML_Sample} - -["type": "JsonProperty",]{.HTML_Sample} - -[  "jsons": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[{]{.HTML_Sample} - -[        "json": [ ]{.HTML_Sample} - -[          {]{.HTML_Sample} - -[            "id": "85a6cc52-0589-45f9",]{.HTML_Sample} - -[            "value": "Overstay 60 minutes"]{.HTML_Sample} - -[          }]{.HTML_Sample} - -[        ],]{.HTML_Sample} - -[      },]{.HTML_Sample} - -["2022-08-09T18:25:02Z"]{.HTML_Sample} - -[],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[{]{.HTML_Sample} - -[        "json": []{.HTML_Sample} - -[          {]{.HTML_Sample} - -[            "id": "85a6cc52-0589-45f9",]{.HTML_Sample} - -[            "value]{.HTML_Sample}[": "Overstay 60 minutes"]{.HTML_Sample} - -[          },]{.HTML_Sample} - -[          {]{.HTML_Sample} - -[            "id": "x5c56s-0589-45f9",]{.HTML_Sample} - -[            "value": "Overstay 45 minutes"]{.HTML_Sample} - -[          }]{.HTML_Sample} - -[        ]]{.HTML_Sample} - -[      },]{.HTML_Sample} - -["2022-08-10T18:25:02Z"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[]]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["vocabs"]{.HTML_Code}. The value of the referred ["vocabs"]{.HTML_Code} 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"]{.HTML_Code}, where the value shall correspond to a [VocabProperty]{.HTML_Keyboard} *vocab* and the second element shall correspond to the associated Temporal Property (for instance *observedAt*). -::: - -::: EX -EXAMPLE 5: -::: - -["gender": {]{.HTML_Sample} - -["type": "VocabProperty",]{.HTML_Sample} - -[  "vocabs": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[{"vocab": "Male"},]{.HTML_Sample} - -["2022-08-09T18:25:02Z"]{.HTML_Sample} - -[],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[{"vocab": "Female"},]{.HTML_Sample} - -["2022-08-10T18:25:02Z"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[]]{.HTML_Sample} - -::: B1plus -[}]{.HTML_Sample} -::: - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["objects"]{.HTML_Code}. The value of the referred ["objects"]{.HTML_Code} 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*). -::: - -::: EX -EXAMPLE 6: -::: - -["spouse": {]{.HTML_Sample} - -[  "type": "Relationship",]{.HTML_Sample} - -[  "objects": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[      "urn:ngsi-ld:Person:123455",]{.HTML_Sample} - -[      "2022-08-09T18:25:02Z"]{.HTML_Sample} - -[    ],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[      "urn:ngsi-ld:Person:999999",]{.HTML_Sample} - -[      "2022-08-10T18:25:02Z"]{.HTML_Sample} - -[    ]]{.HTML_Sample} - -[  ]]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: EX -EXAMPLE 7: -::: - -["activeDevices": {]{.HTML_Sample} - -[  "type": "Relationship",]{.HTML_Sample} - -[  "objects": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562"],]{.HTML_Sample} - -[      "2022-08-09T18:25:02Z"]{.HTML_Sample} - -[],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["urn:ngsi-ld:Device:14142", "urn:ngsi-ld:Device:13562", "urn:ngsi-ld:Device:37309"],]{.HTML_Sample} - -[      "2022-08-10T18:25:02Z"]{.HTML_Sample} - -[]]{.HTML_Sample} - -[  ]]{.HTML_Sample} - -[}]{.HTML_Sample} - -::: B1plus -- 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"]{.HTML_Code}. Such JSON-LD object shall only contain a member whose key shall be ["objectLists"]{.HTML_Code}. The value of the referred[ "objectLists"]{.HTML_Code} 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*). -::: - -::: EX -EXAMPLE 7: -::: - -["membersPresent": {]{.HTML_Sample} - -[  "type": "ListRelationship",]{.HTML_Sample} - -[  "objectLists": []{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]]{.HTML_Sample}[,]{.HTML_Sample} - -[      "2022-08-09T18:25:02Z"]{.HTML_Sample} - -[    ],]{.HTML_Sample} - -[    []{.HTML_Sample} - -[      ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Eve", "urn:ngsi-ld:Person:Mallory"]]{.HTML_Sample}[,]{.HTML_Sample} - -[      "2022-08-10T18:25:02Z"]{.HTML_Sample} - -[    ]]{.HTML_Sample} - -[  ]]{.HTML_Sample} - -[}]{.HTML_Sample} - -### 4.5.10 Entity Type List Representation {#tabentity-type-list-representation number="9.5.11"} - -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** - -::: B1plus -- ["id"]{.HTML_Code} whose value shall be a URI that identifies the entity type list. -- ["type"]{.HTML_Code}: the fixed value ["EntityTypeList"]{.HTML_Code}. -- ["typeList"]{.HTML_Code}: JSON-LD array containing the entity type names. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code} a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -::: - -### 4.5.11 Detailed Entity Type List Representation {#tabdetailed-entity-type-list-representation number="9.5.12"} - -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** - -::: B1plus -- ["attributeNames"]{.HTML_Code}: JSON-LD array containing the names of attributes that instances of the entity type can have. -- ["id"]{.HTML_Code} whose value shall be the URI that identifies the entity type. -- ["type"]{.HTML_Code}: the fixed value ["EntityType"]{.HTML_Code}. -- ["typeName"]{.HTML_Code}: name of entity type, short name if contained in *\@context*. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code} a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -::: - -### 4.5.12 Entity Type Information Representation {#tabentity-type-information-representation number="9.5.13"} - -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** - -::: B1plus -- ["id"]{.HTML_Code} whose value shall be the URI that identifies the entity type. -- ["type"]{.HTML_Code}: the fixed value ["EntityTypeInfo"]{.HTML_Code}. -- ["typeName"]{.HTML_Code}: the URI that identifies the entity type (short name in case of availability in *\@context*). -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code} a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -::: - -### 4.5.13 Attribute List Representation {#tabattribute-list-representation number="9.5.14"} - -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** - -::: B1plus -- ["attributeList"]{.HTML_Code}: JSON-LD array containing the attribute names. -- ["id"]{.HTML_Code}: whose value shall be a URI that identifies the attribute list. -- ["type"]{.HTML_Code}: the fixed value ["AttributeList"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code}: a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -::: - -### 4.5.14 Detailed Attribute List Representation {#tabdetailed-attribute-list-representation number="9.5.15"} - -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** - -::: B1plus -- ["attributeName"]{.HTML_Code}: the URI that identifies the attribute (short name in case of availability in *\@context*). -- ["id"]{.HTML_Code}: whose value shall be the URI that identifies the attribute. -- ["type"]{.HTML_Code}: the fixed value ["Attribute"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code}: a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -- ["typeNames"]{.HTML_Code}: 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 {#tabattribute-information-representation number="9.5.16"} - -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** - -::: B1plus -- ["attributeName"]{.HTML_Code}: the URI that identifies the attribute (short name in case of availability in *\@context*). -- ["id": ]{.HTML_Code}whose value shall be the URI that identifies the attribute. -- ["type"]{.HTML_Code}: the fixed value ["Attribute"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code}: a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -- ["attributeCount"]{.HTML_Code}: number of instances of this attribute. -- ["attributeTypes":]{.HTML_Code} an array of attribute types (e.g. Property, Relationship, GeoProperty) for which instances with the attribute name exist. -- ["typeNames":]{.HTML_Code} 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 {#tabgeojson-representation-of-entities number="9.5.17"} - -#### 4.5.16.0 Foreword {#tabforeword number="9.5.17.1"} - -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]](7-tabreferences.md#8) and/or GeoJSON-LD [[i.20]](7-tabreferences.md#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 {#tabtop-level-geometry-field-selection-algorithm number="9.5.17.2"} - -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"]{.HTML_Code} shall be used. - -If the selected *GeoProperty* has multiple instances as described in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support), 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 {#tabgeojson-representation-of-an-individual-entity number="9.5.17.3"} - -The GeoJSON representation of a spatially bounded Entity is defined as a single GeoJSON *Feature* object including the following members: - -**Mandatory** - -::: B1plus -- ["geometry"]{.HTML_Code}: 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"]{.HTML_Code}: the Entity id. -- ["properties"]{.HTML_Code}: A JSON object containing the following members: -::: - -::: B2plus -- ["type"]{.HTML_Code}: 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](9-tabcontext-information-management-framework.md#tabngsi-ld-property-representations). In case of multiple *Property* instances with the same Property name as described in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support), all instances are provided as an unordered JSON array. -- One member for each *Relationship* as per the rules stated in [clause 4.5.3](9-tabcontext-information-management-framework.md#tabngsi-ld-relationship-representations). In case of multiple *Relationship* instances with the same Relationship name as described in [clause 4.5.5](9-tabcontext-information-management-framework.md#tabmulti-attribute-support), all instances are provided as an unordered JSON array. -::: - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value["Feature"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- A JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) if requested as part of the payload body. -::: - -This representation shall be fully compliant with *Feature* as defined within IETF RFC 7946 [[8]](7-tabreferences.md#8). - -An example can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.3](15-annex-c-informative-examples-of-using-the-api.md#c.2.3tabparking-entity). - -#### 4.5.16.3 GeoJSON Representation of Multiple Entities {#tabgeojson-representation-of-multiple-entities number="9.5.17.4"} - -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** - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value ["FeatureCollection"]{.HTML_Code}. -- ["features"]{.HTML_Code}: a JSON array of GeoJSON *Feature* objects as defined in [clause 4.5.16.2](9-tabcontext-information-management-framework.md#tabgeojson-representation-of-an-individual-entity). Note that separate *\@context* elements for each *Feature* will not be present in the payload body. -::: - -**Optional** - -::: B1plus -- A JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) if requested as part of the payload body. -::: - -This representation shall be fully compliant with *FeatureCollection* as defined within IETF RFC 7946 [[8]](7-tabreferences.md#8). - -An example can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.3](15-annex-c-informative-examples-of-using-the-api.md#c.2.3tabparking-entity). - -### 4.5.17 Simplified GeoJSON Representation of Entities {#tabsimplified-geojson-representation-of-entities number="9.5.18"} - -#### 4.5.17.0 Foreword {#tabforeword-1 number="9.5.18.1"} - -When both simplified (see [clause 4.5.4](9-tabcontext-information-management-framework.md#tabsimplified-representation)) 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 {#tabsimplified-geojson-representation-of-an-individual-entity number="9.5.18.2"} - -The simplified GeoJSON representation of a spatially bounded Entity is defined as a single GeoJSON *Feature* object as follows: - -**Mandatory** - -::: B1plus -- ["geometry"]{.HTML_Code}: The value of the selected *GeoProperty* (a GeoJSON geometry object) used to define the spatial location of the Entity. -- ["id"]{.HTML_Code}: the Entity id. -- ["type"]{.HTML_Code}: the fixed value ["Feature"]{.HTML_Code}. -- ["properties"]{.HTML_Code}: An array containing the following attributes: -::: - -::: B2plus -- ["type"]{.HTML_Code}: **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"]{.HTML_Code}, 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"]{.HTML_Code}. -- 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"]{.HTML_Code} 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"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- A JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) if requested as part of the payload body. -::: - -The selection of the geometry field is defined in [clause 4.5.16.1](9-tabcontext-information-management-framework.md#tabtop-level-geometry-field-selection-algorithm). - -This representation shall be fully compliant with *Feature* as defined within IETF RFC 7946 [[8]](7-tabreferences.md#8). - -An example can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.3](15-annex-c-informative-examples-of-using-the-api.md#c.2.3tabparking-entity). - -#### 4.5.17.2 Simplified GeoJSON Representation of multiple Entities {#tabsimplified-geojson-representation-of-multiple-entities number="9.5.18.3"} - -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** - -::: B1plus -- ["features"]{.HTML_Code}: a JSON array of simplified GeoJSON *Feature* objects as defined in [clause 4.5.17.1](9-tabcontext-information-management-framework.md#tabsimplified-geojson-representation-of-an-individual-entity). Note that separate *\@context* elements for each *Feature* will not be present in the payload body. -- ["type"]{.HTML_Code}: the fixed value ["FeatureCollection"]{.HTML_Code}. -::: - -**Optional** - -::: B1plus -- A JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context) if requested as part of the payload body. -::: - -This representation shall be fully compliant with *FeatureCollection* as defined within IETF RFC 7946 [[8]](7-tabreferences.md#8). - -### 4.5.18 NGSI-LD LanguageProperty Representations {#tabngsi-ld-languageproperty-representations number="9.5.19"} - -#### 4.5.18.1 Introduction {#tabintroduction-8 number="9.5.19.1"} - -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](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type *LanguageProperty* as per [clause 4.5.18.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-languageproperty) (when in normalized representation) or [clause 4.5.18.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-languageproperty) (when in concise representation). - -Both normalized and concise representation of *LanguageProperties* shall be supported by implementations and can be selected by [Context Consumers]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.18.2 Normalized NGSI-LD LanguageProperty {#tabnormalized-ngsi-ld-languageproperty number="9.5.19.2"} - -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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), with the following differences: - -**Mandatory** - -- ::: B1plus - ["languageMap"]{.HTML_Code}: a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [[28]](7-tabreferences.md#28) or the language tag ["@none"]{.HTML_Code} which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized *value*. - ::: - - ::: B1plus - An NGSI-LD Null used during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) shall be encoded as the JSON object [{"@none": "urn:ngsi-ld:null"}]{.HTML_Code}. The same representation is also used to indicate a deletion in notifications and in temporal evolutions for encoding a deleted *LanguageProperty*[.]{.HTML_Definition} - ::: - -- ::: B1plus - ["type"]{.HTML_Code}: the fixed value ["LanguageProperty"]{.HTML_Code}. - ::: - -**Output Only** - -::: B1plus -- ["previousLanguageMap"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD *LanguageProperty* in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as language maps are always strings and hence unitless. -- ["value" ]{.HTML_Code}and ["previousValue"]{.HTML_Code}: shall never be present, as *value* is a generalization of *languageMap*. -::: - -#### 4.5.18.3 Concise NGSI-LD LanguageProperty {#tabconcise-ngsi-ld-languageproperty number="9.5.19.3"} - -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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), with the following differences: - -**Mandatory** - -- ::: B1plus - ["languageMap"]{.HTML_Code}: a JSON object consisting of a set of a non-empty language tags as defined by IETF RFC 5646 [[28]](7-tabreferences.md#28) or the language tag ["@none" ]{.HTML_Code}which represents a default language, with each language tag mapping to a single string or array of strings. It represents a more specialized *value*. - ::: - - ::: B1plus - An NGSI-LD Null used during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) shall be encoded as the JSON object [{"@none": "urn:ngsi-ld:null"}]{.HTML_Code}. The same representation is also used to indicate a deletion in notifications and the temporal evolutions for encoding a deleted *LanguageProperty*. - ::: - -**Optional** - -::: B1plus -- ["type"]{.HTML_Code}: If missing, ["LanguageProperty"]{.HTML_Code} can be inferred by the presence of the ["languageMap"]{.HTML_Code} attribute. -::: - -**Output Only** - -::: B1plus -- ["previousLanguageMap"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD *LanguageProperty* in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as language maps are always strings and hence unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as it is a generalization of ["languageMap"]{.HTML_Code}. -::: - -Notwithstanding the definition above, during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)), 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]{.HTML_Code}[-]{.HTML_Code}[ld:null"]{.HTML_Code}*.* - -### 4.5.19 Aggregated temporal representation of an Entity {#tabaggregated-temporal-representation-of-an-entity number="9.5.20"} - -#### 4.5.19.0 Foreword {#tabforeword-2 number="9.5.20.1"} - -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]{.HTML_Keyboard} through specific request parameters. An example can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.14](15-annex-c-informative-examples-of-using-the-api.md#c.5.14tabtemporal-query-aggregated-representation). - -The aggregation function is applied according to the following principles: - -::: B1plus -- An aggregation method specifies the function used to aggregate the values (e.g. sum, mean, etc.). A [Context Consumer]{.HTML_Keyboard} 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: - -::: B1plus -- A JSON-LD object containing the following members: -::: - -::: B2plus -- *id*, *type* and *\@context* as described in [clause 4.5.1](9-tabcontext-information-management-framework.md#tabngsi-ld-entity-representation). -- 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"]{.HTML_Code}. Such JSON-LD object shall contain one member per aggregation method requested by the [Context Consumer]{.HTML_Keyboard}. 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: -::: - -::: B3 -1) the value obtained after applying the aggregation method over the period; -::: - -::: B3 -2) the start *DateTime* of the corresponding period; -::: - -::: B3 -3) the end *DateTime* of the corresponding period. -::: - -::: B2plus -- 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"]{.HTML_Code}. Such JSON-LD object shall contain one member per aggregation method requested by the [Context Consumer]{.HTML_Keyboard}. 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: -::: - -::: B3 -1) the value obtained after applying the aggregation method over the period; -::: - -::: B3 -2) the start *DateTime* of the corresponding period; -::: - -::: B3 -3) the end *DateTime* of the corresponding period. -::: - -An example of this aggregated temporal representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.14](15-annex-c-informative-examples-of-using-the-api.md#c.5.14tabtemporal-query-aggregated-representation). - -#### 4.5.19.1 Supported behaviours for aggregation functions {#tabsupported-behaviours-for-aggregation-functions number="9.5.20.2"} - -In order to support such aggregation functions, two parameters are defined: - -::: B1plus -- *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]](7-tabreferences.md#17) Duration Representation and in particular using the following format and conventions: - -::: B1plus -- The duration shall be a string in the format [P[n]Y[n]M[n]DT[n]H[n]M[n]S]{.HTML_Code} or [P[n]W]{.HTML_Code}, where [[n]]{.HTML_Code} is replaced by the value for each of the date and time elements that follow the [[n]]{.HTML_Code}, [P]{.HTML_Code} is the duration designator and [T]{.HTML_Code} is the time designator. For example, ["P3Y6M4DT12H30M5S"]{.HTML_Code} 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"]{.HTML_Code} or ["P0D"]{.HTML_Code}) 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: - -::: B1plus -- [aggrMethods = "avg" / "distinctCount" / "max" / "min" / "stddev" / "sum" / "sumsq" / "totalCount"]{.PL} -::: - -The semantics of the different aggregation methods defined above is as follows, and shall be supported by compliant implementations: - -::: {#Table_4.5.19.1-1 .TH} -Table 4.5.19.1-1: Semantics of aggregation methods for Properties on JSON native data types -::: - -::: TAC -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| Aggregation Method | JSON String | JSON Number | JSON Object | JSON Array | JSON Boolean | -| | | | | | | -| | | | | | (see note) | -+====================+======================================================================+==================================================================+====================+===========================================================================+==================================================================+ -| avg | N/A | Calculate the average of the values inside the period | N/A | Calculate the average number of the sizes of the arrays inside the period | Calculate the average of the values inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| distinctCount | Calculate the count of distinct values inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| max | Calculate the last value in lexicographical order inside the period | Calculate the maximum value inside the period | N/A | Calculate the maximum size of the arrays inside the period | Calculate the maximum value inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| min | Calculate the first value in lexicographical order inside the period | Calculate the minimum value inside the period | N/A | Calculate the minimum size of the arrays inside the period | Calculate the minimum value inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| stddev | N/A | Calculate the standard deviation of the values inside the period | N/A | N/A | Calculate the standard deviation of the values inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| sum | N/A | Calculate the sum of the values inside the period | N/A | Calculate the sum of the sizes of the arrays inside the period | Calculate the sum of the values inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| sumsq | N/A | Calculate the sum of the square of the values inside the period | N/A | N/A | Calculate the sum of the square of the values inside the period | -+--------------------+----------------------------------------------------------------------+------------------------------------------------------------------+--------------------+---------------------------------------------------------------------------+------------------------------------------------------------------+ -| totalCount | Calculate the number of times the value has been updated inside the period | -+--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ::: TAN | -| NOTE: | -| | -| For the purpose of aggregation, *true* is considered as a value of 1, *false* is considered as a value of 0. | -| ::: | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_4.5.19.1-2 .TH} -Table 4.5.19.1-2: Semantics of aggregation methods for Properties on other supported data types -::: - -::: TAC -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| {TAC} | {TAC} | {TAC} | {TAC} | {TAC} | -| | | | | | -| **Aggregation Method** | **DateTime** | **Date** | **Time** | **URI** | -+========================+===============================================+===============================================+=====================================================================================================================================================+======================+ -| avg | N/A | N/A | Calculate the average time inside the period (e.g. to apply on an event that occurs at non fixed times, like the time a car enters a given parking) | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| distinctCount | Calculate the count of distinct values inside the period | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| max | Calculate the maximum value inside the period | Calculate the maximum value inside the period | Calculate the maximum value inside the period | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| min | Calculate the minimum value inside the period | Calculate the minimum value inside the period | Calculate the minimum value inside the period | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| stddev | N/A | N/A | N/A | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| sum | N/A | N/A | N/A | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| sumsq | N/A | N/A | N/A | N/A | -+------------------------+-----------------------------------------------+-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+----------------------+ -| totalCount | Calculate the number of times the value has been updated inside the period | -+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -::: - -::: {#Table_4.5.19.1-3 .TH} -Table 4.5.19.1-3: Semantics of aggregation methods for Relationships -::: - -::: TAL -+-----------------------------------+-----------------------------------------------------------------------------------+ -| {TAL} | {TAC} | -| | | -| **Aggregation Method** | **Relationship** | -+:=================================:+===================================================================================+ -| avg | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| distinctCount | {TAC} | -| | | -| | Calculate the count of distinct relationships targets inside the period | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| max | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| min | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| stddev | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| sum | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| sumsq | {TAC} | -| | | -| | N/A | -+-----------------------------------+-----------------------------------------------------------------------------------+ -| totalCount | {TAC} | -| | | -| | Calculate the number of times the relationship has been updated inside the period | -+-----------------------------------+-----------------------------------------------------------------------------------+ -::: - -### 4.5.20 NGSI-LD VocabProperty Representations {#tabngsi-ld-vocabproperty-representations number="9.5.21"} - -#### 4.5.20.1 Introduction {#tabintroduction-9 number="9.5.21.1"} - -NGSI-LD defines a specialized type of Property named [VocabProperty]{.HTML_Keyboard}, defined by the NGSI-LD *\@context* described by the present document in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type [VocabProperty]{.HTML_Keyboard} as per [clause 4.5.20.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-vocabproperty) (when in normalized representation) or [clause 4.5.20.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-vocabproperty) (when in concise representation). - -Both normalized and concise representation of [Vocab]{.HTML_Keyboard}[Properties]{.HTML_Keyboard} shall be supported by implementations and can be selected by [Context Consumers]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.20.2 Normalized NGSI-LD VocabProperty {#tabnormalized-ngsi-ld-vocabproperty number="9.5.21.2"} - -An NGSI-LD [VocabProperty]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), with the following differences: - -**Mandatory** - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value ["]{.HTML_Code}[VocabProperty]{.HTML_Keyboard}["]{.HTML_Code}. -- ["vocab"]{.HTML_Code}: 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** - -::: B1plus -- ["previousVocab"]{.HTML_Code}: only provided in case of notifications and only if the *showChanges* option is explicitly requested. It represents the previous [VocabProperty]{.HTML_Keyboard} *vocab*, before the triggering change. The representation is the same as that of ["vocab"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD [VocabProperty]{.HTML_Keyboard} in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as vocabs are always strings and hence unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as *value* is a generalization of *vocab*. -::: - -#### 4.5.20.3 Concise NGSI-LD VocabProperty {#tabconcise-ngsi-ld-vocabproperty number="9.5.21.3"} - -An NGSI-LD [VocabProperty]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), with the following differences. - -**Mandatory** - -::: B1plus -- ["vocab":]{.HTML_Code} 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** - -::: B1plus -- ["type"]{.HTML_Code}: If missing, ["]{.HTML_Code}[VocabProperty]{.HTML_Keyboard}["]{.HTML_Code} can be inferred by the presence of the ["vocab"]{.HTML_Code} attribute. -::: - -**Output Only** - -::: B1plus -- ["previousVocab"]{.HTML_Code}: only provided only in the case of notifications and only if the *showChanges* option is explicitly requested. It represents the previous [VocabProperty]{.HTML_Keyboard} *vocab*, before the triggering change. The representation is the same as that of ["vocab"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD [VocabProperty]{.HTML_Keyboard} in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as vocabs are always strings and hence unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as it is a generalization of *vocab*. -::: - -### 4.5.21 NGSI-LD ListProperty Representations {#tabngsi-ld-listproperty-representations number="9.5.22"} - -#### 4.5.21.1 Introduction {#tabintroduction-10 number="9.5.22.1"} - -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](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type *ListProperty* as per [clause 4.5.21.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-listproperty) (when in normalized representation) or [clause 4.5.21.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listproperty) (when in concise representation). - -Both normalized and concise representation of *ListProperties* shall be supported by implementations and can be selected by [Context Consumers]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.21.2 Normalized NGSI-LD ListProperty {#tabnormalized-ngsi-ld-listproperty number="9.5.22.2"} - -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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), with the following differences: - -**Mandatory** - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value ["]{.HTML_Code}*ListProperty*["]{.HTML_Code}*.* -- ["valueList"]{.HTML_Code}: a JSON representation ordered array of Property Values (see definition of NGSI-LD Value in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)). It represents a more specialized *value*. -::: - -::: B1 -An array consisting of a single NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["valueList"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *ListProperty*, as well as in notifications and in temporal evolutions (for encoding a deleted *ListProperty*). -::: - -**Output Only** - -::: B1plus -- ["previousValueList"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD *ListProperty* in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as *value* is a generalization of *valueList*. -::: - -#### 4.5.21.3 Concise NGSI-LD ListProperty {#tabconcise-ngsi-ld-listproperty number="9.5.22.3"} - -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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), with the following differences: - -**Mandatory** - -::: B1plus -- ["valueList"]{.HTML_Code}: a JSON representation of a ordered array of Property Values (see definition of NGSI-LD Value in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)). It represents a more specialized *value*. -::: - -::: B1 -An array consisting of a single NGSI-LD Null (explained in [clause 4.5.0](9-tabcontext-information-management-framework.md#tabintroduction-4) and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["valueList"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *ListProperty*, as well as in notifications and in temporal evolutions (for encoding a deleted *ListProperty*). -::: - -**Optional** - -::: B1plus -- ["type"]{.HTML_Code}: If missing, ["]{.HTML_Code}*ListProperty*["]{.HTML_Code} can be inferred by the presence of the ["valueList"]{.HTML_Code} attribute. -::: - -**Output Only** - -::: B1plus -- ["previousValueList"]{.HTML_Code}: only provided only in the case of notifications and only if the *showChanges* option is explicitly requested. It represents the previous *ListProperty* ["valueList"]{.HTML_Code}, before the triggering change. The representation is the same as that of ["valueList"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD *ListProperty* in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["value"]{.HTML_Code} and ["previousValue]{.HTML_Code}": shall never be present, as *value* is a generalization of *valueList*. -::: - -### 4.5.22 NGSI-LD ListRelationship Representations {#tabngsi-ld-listrelationship-representations number="9.5.23"} - -#### 4.5.22.1 Introduction {#tabintroduction-11 number="9.5.23.1"} - -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](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type *ListRelationship* as per [clause 4.5.22.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-listrelationship) (when in normalized representation) or [clause 4.5.22.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-listrelationship) (when in concise representation). - -Both normalized and concise representation of *ListRelationships* shall be supported by implementations and can be selected by [Context Consumers]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.22.2 Normalized NGSI-LD ListRelationship {#tabnormalized-ngsi-ld-listrelationship number="9.5.23.2"} - -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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-relationship), with the following differences: - -**Mandatory** - -::: B1plus -- ["objectList"]{.HTML_Code}: 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"]{.HTML_Code} and its value holding the *Relationship's* object represented by a URI. -::: - -::: B1 -An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["objectList"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *ListRelationship*, as well as in notifications and in temporal evolutions (for encoding a deleted *ListRelationship*). -::: - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value ["]{.HTML_Code}*ListRelationship*["]{.HTML_Code}. -::: - -**Output Only** - -::: B1plus -- ["entityList":]{.HTML_Code} only provided in case of [Linked Entity]{.HTML_Keyboard} **retrieval**, and only if the inline *join* option is explicitly requested (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), where it is used to define the target [Linked Entities]{.HTML_Keyboard} of a *ListRelationship's* *objectList* in **normalized** **representation**. -- ["previousObjectList"]{.HTML_Code}: 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".]{.HTML_Code} -::: - -Furthermore, an NGSI-LD *ListRelationship* in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entity"]{.HTML_Code}: shall never be present as *entity* is a generalization of *entityList*. -- ["object"]{.HTML_Code} and ["previousObject"]{.HTML_Code}: shall never be present as *object* is a generalization of *objectList*. -::: - -#### 4.5.22.3 Concise NGSI-LD ListRelationship {#tabconcise-ngsi-ld-listrelationship number="9.5.23.3"} - -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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-relationship), with the following differences: - -**Mandatory** - -::: B1plus -- ["objectList"]{.HTML_Code}: this represents a more specialized *object* and is represented by an ordered array of either: -::: - -::: B2plus -- a JSON objects containing a single Attribute with a key called ["object"]{.HTML_Code} 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"]{.HTML_Code} attribute. -::: - -::: B1 -An array consisting of a single NGSI-LD Null (explained in 4.5.0 and defined in [clause 3.1](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) can be used as the right-hand side of the ["objectList"]{.HTML_Code} during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) to indicate a deletion of the *ListRelationship*, as well as in notifications and in temporal evolutions (for encoding a deleted *ListRelationship*). -::: - -**Optional** - -::: B1plus -- ["type"]{.HTML_Code}: If missing, ["ListRelationship"]{.HTML_Code} can be inferred by the presence of the ["objectList"]{.HTML_Code} attribute. -::: - -**Output Only** - -::: B1plus -- ["entityList"]{.HTML_Code}: only provided if the inline *join* option is explicitly requested (see [clause 4.5.23.2](9-tabcontext-information-management-framework.md#tabinline-linked-entity-representation)), where it is used to define the target [Linked Entities]{.HTML_Keyboard} of a *ListRelationship's* ["objectList"]{.HTML_Code} in **concise** **representation**. -- ["previousObjectList"]{.HTML_Code}: 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"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD *ListRelationship* in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["entity"]{.HTML_Code}: shall never be present as *entity* is a generalization of *entityList*. -- ["object"]{.HTML_Code} and ["previousObject"]{.HTML_Code}: shall never be present as *object* is a generalization of *objectList*. -::: - -### 4.5.23 NGSI-LD Linked Entity Retrieval {#tabngsi-ld-linked-entity-retrieval number="9.5.24"} - -#### 4.5.23.1 Introduction {#tabintroduction-12 number="9.5.24.1"} - -Since Entities are uniquely identifiable by a URI, it is possible to traverse across the Entity graph directly from a [Linking Entity]{.HTML_Keyboard} to a [Linked Entity]{.HTML_Keyboard}. It is therefore sometimes convenient to be able to query or retrieve data via a single [Context Broker]{.HTML_Keyboard} request and to receive a response including both [Linking Entities]{.HTML_Keyboard} and dependent [Linked Entities]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language)) and the complete serialization of an Entity and its dependents. - -When retrieving [Linked Entities]{.HTML_Keyboard}, 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]{.HTML_Keyboard} are considered to be retrievable in this manner. - -#### 4.5.23.2 Inline Linked Entity Representation {#tabinline-linked-entity-representation number="9.5.24.2"} - -With the inline representation, the [Context Broker]{.HTML_Keyboard} response shall only consist of [Linking Entities]{.HTML_Keyboard} - either a single [Linking Entity]{.HTML_Keyboard}, or an array consisting of [Linking Entities]{.HTML_Keyboard}. The additional Entity data from [Linked Entities]{.HTML_Keyboard} 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](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.23.3 Flattened Linked Entity Representation {#tabflattened-linked-entity-representation number="9.5.24.3"} - -With the flattened representation, the [Context Broker]{.HTML_Keyboard} response shall always consist of an array of Entities. This array will consist of both [Linking Entities]{.HTML_Keyboard} and [Linked Entities]{.HTML_Keyboard} (where the retrieved [Linked Entities]{.HTML_Keyboard} defined by an annotated *Relationship*), are appended to the array. This flattened representation allows for batch operations (see clauses [5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation), [5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert), [5.6.9](10-tabapi-operation-definition.md#tabbatch-entity-update) and [5.6.10](10-tabapi-operation-definition.md#tabbatch-entity-delete)) be applied directly using the response from the [Context Broker]{.HTML_Keyboard}. - -::: ondemand_PAR_space_after_10 -An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). -::: - -### 4.5.24 NGSI-LD JsonProperty Representations {#tabngsi-ld-jsonproperty-representations number="9.5.25"} - -#### 4.5.24.1 Introduction {#tabintroduction-13 number="9.5.25.1"} - -NGSI-LD defines a specialized type of Property named [JsonProperty]{.HTML_Keyboard}, defined by the NGSI-LD *\@context* described by the present document in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -When dealing with NGSI-LD Entities, implementations shall interpret the JSON-LD nodes of type [JsonProperty]{.HTML_Keyboard} as per [clause 4.5.24.2](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-jsonproperty) (when in normalized representation) or [clause 4.5.24.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-jsonproperty) (when in concise representation). - -Both normalized and concise representation of [JsonProperties]{.HTML_Keyboard} shall be supported by implementations and can be selected by [Context Consumers]{.HTML_Keyboard} through specific request parameters. An example of this representation can be found in [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.md#c.2.2tabvehicle-entity). - -#### 4.5.24.2 Normalized NGSI-LD JsonProperty {#tabnormalized-ngsi-ld-jsonproperty number="9.5.25.2"} - -An NGSI-LD [JsonProperty]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabnormalized-ngsi-ld-property), with the following differences: - -**Mandatory** - -::: B1plus -- ["type"]{.HTML_Code}: the fixed value ["]{.HTML_Code}[JsonProperty]{.HTML_Keyboard}["]{.HTML_Code}. -- ["json"]{.HTML_Code}: 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** - -::: B1plus -- ["previousJson"]{.HTML_Code}: only provided in case of notifications and only if the [showChanges]{.HTML_Variable} option is explicitly requested. It represents the previous [JsonProperty]{.HTML_Keyboard} *json*, before the triggering change. The representation is the same as that of ["json"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD [JsonProperty]{.HTML_Keyboard} in the normalized representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as raw JSON objects are unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as *value* is a generalization of *json*. -::: - -#### 4.5.24.3 Concise NGSI-LD JsonProperty {#tabconcise-ngsi-ld-jsonproperty number="9.5.25.3"} - -An NGSI-LD [JsonProperty]{.HTML_Keyboard} 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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), with the following differences: - -**Mandatory** - -::: B1plus -- ["json"]{.HTML_Code}: 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** - -::: B1plus -- ["type"]{.HTML_Code}: If missing, ["]{.HTML_Code}[JsonProperty]{.HTML_Keyboard}["]{.HTML_Code} can be inferred by the presence of the ["json"]{.HTML_Code} attribute. -::: - -**Output Only** - -::: B1plus -- ["previousJson"]{.HTML_Code}: only provided in case of notifications and only if the [showChanges]{.HTML_Variable} option is explicitly requested. It represents the previous [JsonProperty]{.HTML_Keyboard} *json*, before the triggering change. The representation is the same as that of ["json"]{.HTML_Code}. -::: - -Furthermore, an NGSI-LD [JsonProperty]{.HTML_Keyboard} in the concise representation shall never include the following members: - -**Prohibited** - -::: B1plus -- ["unitCode"]{.HTML_Code}: shall never be present, as raw JSON objects are unitless. -- ["value"]{.HTML_Code} and ["previousValue"]{.HTML_Code}: shall never be present, as it is a generalization of *json*. -::: - -### 4.5.25 NGSI-LD EntityMap Representation {#tabngsi-ld-entitymap-representation number="9.5.26"} - -The EntityMap representation is used by [Context Brokers]{.HTML_Keyboard} to ensure unity when querying across distributed operations. It is an active mapping of [Context Source Registrations]{.HTML_Keyboard} to Entities which are relevant to an ongoing Context Information Consumption request (see [clause 4.3.6.7](9-tabcontext-information-management-framework.md#tabquerying-and-retrieving-distributed-entities-as-unitary-operations)). The EntityMap representation shall be a JSON-LD object containing the following members: - -**Mandatory** - -::: B1plus -- ["id"]{.HTML_Code}: whose value shall be the URI that identifies the attribute. -- ["type"]{.HTML_Code}: the fixed value ["EntityMap"]{.HTML_Code}. -- ["expiredBy"]{.HTML_Code}: a DateTime string (as defined in [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)) for encoding a timestamp indicating the time at which the EntityMap can no longer be used. -::: - -**Optional** - -::: B1plus -- ["@context"]{.HTML_Code}: a JSON-LD *\@context* as described in [clause 4.4](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). -::: - -**Output Only** - -::: B1plus -- ["entityMap"]{.HTML_Code}: 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"]{.HTML_Code}: a JSON-LD index map holding a unique list of [Context Source Registrations]{.HTML_Keyboard} ids (URIs) each of which lists the *entityMap* used by a [Context Source]{.HTML_Keyboard}. -::: - -## 4.6 Data Representation Restrictions {#tabdata-representation-restrictions number="9.6"} - -### 4.6.1 Supported text encodings {#tabsupported-text-encodings number="9.6.1"} - -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 {#tabsupported-names number="9.6.2"} - -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: - -``` json -nameChar = unicodeNumber / unicodeLetter -nameChar =/ %x5F          ; _ -name = unicodeLetter *nameChar -``` - -::: B1plus -- *unicodeNumber* is any Unicode character that has *Number* as a Category [[22]](7-tabreferences.md#22). With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by [\\p{N}]{.HTML_Code}. -- *unicodeLetter* is any Unicode character that has *Letter* as a Category [[22]](7-tabreferences.md#22). With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by [\\p{L}]{.HTML_Code}. -::: - -In order to avoid name clashing, names can be prefixed as specified by the following BNF grammar: - -``` json -prefix = unicodeLetter *nameChar -name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name -``` - -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 {#tabsupported-data-types-for-values number="9.6.3"} - -Compliant NGSI-LD implementations shall support the following data types for representing Values: - -::: B1plus -- All the JSON native data types as mandated by IETF RFC 8259 [[6]](7-tabreferences.md#6), section 3. -- All the GeoJSON *Geometries* [[8]](7-tabreferences.md#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]](7-tabreferences.md#17) Complete Representation and in particular using the 'Extended Format', as described below: -::: - -::: B2plus -- 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]{.HTML_Code} as defined in ISO 8601 [[17]](7-tabreferences.md#17). In this representation, the character ["-"]{.HTML_Code} is used to separate the calendar date components, the character ["T"]{.HTML_Code} is used to indicate the start of the time-of-day portion, the character [":"]{.HTML_Code} is used to separate the time-of-day components, and the trailing character ["Z"]{.HTML_Code} 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]{.HTML_Code}. In requests, also a comma instead of a decimal point may be used as separator for compatibility reasons. -::: - -::: NO -NOTE 1: - -In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [[17]](7-tabreferences.md#17) states that it is the preferred option. However, in practice the decimal point is more commonly used *.* -::: - -::: B2plus -- The trailing timestamp component shall contain the time zone related information and shall always be equal to the character ["Z"]{.HTML_Code}. Therefore, all timestamps shall be expressed in **UTC**. -::: - -::: B1plus -- **Date** string for encoding a calendar date. It uses ISO 8601 [[17]](7-tabreferences.md#17) Complete Representation using the 'Extended Format', as described below: -::: - -::: B2plus -- It shall be a string containing *Year*, *Month*, *Day* components using the format [YYYY-MM-DD]{.HTML_Code} as defined in ISO 8601 [[17]](7-tabreferences.md#17). In this representation, the character ["-"]{.HTML_Code} is used to separate the calendar date components. -- All the referred components shall appear in the string; reduced representations are not permitted. -::: - -::: B1plus -- **Time** string for encoding a local time expressed in **UTC**. It uses ISO 8601 [[17]](7-tabreferences.md#17) Complete Representation using the 'Extended Format', as described below: -::: - -::: B2plus -- It shall be a string containing *Hours*, *Minutes* and *Seconds* components using the format [hh:mm:ssZ]{.HTML_Code} as defined in ISO 8601 [[17]](7-tabreferences.md#17). In this representation, the character [":"]{.HTML_Code} 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]{.HTML_Code}*.* In requests, also a comma instead of a decimal point may be used as separator for compatibility reasons. -::: - -::: NO -NOTE 2: - -In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [[17]](7-tabreferences.md#17) states that it is the preferred option. However, in practice the decimal point is more commonly used. -::: - -::: B2plus -- The string shall not contain expressions of the difference between local time and UTC. All representations shall be interpreted as being expressed in **UTC**. -::: - -::: B1plus -- URI as mandated by ISO 8601 [[17]](7-tabreferences.md#17), Appendix A, production rule named 'URI'. -::: - -Implementations may support additional data types different to those enumerated above, for instance: - -::: B1plus -- 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 {#tabsupported-content number="9.6.4"} - -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: - -::: B1plus -- [%x3C; <]{.HTML_Code} -- [%x3E; >]{.HTML_Code} -- [%x22; "]{.HTML_Code} -- [%x27; ']{.HTML_Code} -- [%x3D; =]{.HTML_Code} -- [%x3B; ;]{.HTML_Code} -- [%x28; (]{.HTML_Code} -- [%x29; )]{.HTML_Code} -::: - -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 {#tabsupported-data-types-for-languagemaps number="9.6.5"} - -Compliant NGSI-LD implementations shall support the following data types for representing LanguageMaps: - -::: B1plus -- A JSON object consisting of a series of key-value pairs where the keys shall be JSON strings representing IETF RFC 5646 [[28]](7-tabreferences.md#28) language codes or the JSON-LD ["@none"]{.HTML_Code} 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"}]{.HTML_Code} shall be used to represent an NGSI-LD Null during partial update patch and merge patch (see clauses [5.5.8](10-tabapi-operation-definition.md#tabpartial-update-patch-behaviour) and [5.5.12](10-tabapi-operation-definition.md#tabmerge-patch-behaviour)) 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 {#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity number="9.6.6"} - -Some services (batch operations, clauses [5.6.7](10-tabapi-operation-definition.md#tabbatch-entity-creation), [5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert), [5.6.9](10-tabapi-operation-definition.md#tabbatch-entity-update) and [5.6.10](10-tabapi-operation-definition.md#tabbatch-entity-delete)) 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 {#tabgeospatial-properties number="9.7"} - -### 4.7.1 GeoJSON Geometries {#tabgeojson-geometries number="9.7.1"} - -Geospatial Properties in NGSI-LD shall be represented using **GeoJSON** Geometries [[8]](7-tabreferences.md#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](9-tabcontext-information-management-framework.md#tabcore-and-user-ngsi-ld-context). - -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]](7-tabreferences.md#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]{.HTML_Keyboard}: - -::: B1plus -- **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]{.HTML_Keyboard} (see [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration)). In this case they represent locations in which Entities with the respective geospatial Properties are contained. For example, a [Context Source]{.HTML_Keyboard} that monitors the location of cars in a city may be represented by a [Context Source Registration]{.HTML_Keyboard} 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 {#tabrepresentation-of-geojson-geometries-in-json-ld number="9.7.2"} - -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]](7-tabreferences.md#6), meeting the syntax and restrictions mandated by IETF RFC 7946 [[8]](7-tabreferences.md#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]{.HTML_Keyboard} should consider the implications in terms of RDF compatibility. - -::: ondemand_PAR_space_after_10 -GeoJSON coordinates shall be considered as consisting of values of a JSON-LD floating point **number** data type. The degree of precision of a latitude and longitude (and optional altitude) held within a context broker will depend upon the implementation. Implementors should note that the GeoJSON specification itself recommends 6 decimal places for latitude and longitude which equates to roughly 10cm of precision. -::: - -### 4.7.3 Concise NGSI-LD GeoProperty {#tabconcise-ngsi-ld-geoproperty number="9.7.3"} - -Notwithstanding the restrictions defined in [clause 4.5.2.3](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property), 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](8-tabdefinition-of-terms-symbols-and-abbreviations.md#tabterms)) which itself is also a supported GeoJSON geometry. - -**Mandatory** - -::: B1plus -- ["type"]{.HTML_Code}: shall be a supported GeoJSON geometry type as defined in [clause 4.7.1](9-tabcontext-information-management-framework.md#tabgeojson-geometries). -- ["coordinates"]{.HTML_Code}: shall be present, as defined by the relevant GeoJSON Geometry [[8]](7-tabreferences.md#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](9-tabcontext-information-management-framework.md#tabconcise-ngsi-ld-property)) with the exception that if the Property *value* resolves to a supported GeoJSON geometry, the type ["GeoProperty"]{.HTML_Code} shall be inferred. - -## 4.8 Temporal Properties {#tabtemporal-properties number="9.8"} - -NGSI-LD defines the following Properties of type *TemporalProperty* that shall be supported by implementations: - -::: B1plus -- **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. -- **expiresAt** is defined as the temporal Property at which the Entity, Property, Relationship, CSourceRegistration, Subscription or Snapshot should be deleted from an NGSI-LD system. -- **lastUsedAt** is defined as the temporal Property at which a Snapshot has been most recently used, i.e. when the most recent operation has been executed on this Snapshot. -::: - -Temporal Properties in NGSI-LD shall be represented based on the *DateTime* data type as mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values). - -::: NO -NOTE 1: - -For simplicity reasons, a *TemporalProperty* is represented only by its Value, i.e. no *Properties* of *TemporalProperty* nor *Relationships* of *TemporalProperty* can be conveyed. In more formal language, a *TemporalProperty* does not allow reification. -::: - -::: NO -NOTE 2: - -It is important to remark that the term *TemporalProperty* has been reserved for the semantic tagging of non-reified structural timestamps ( *observedAt* , *createdAt* , *modifiedAt, deletedAt* , *expiresAt* ), which capture the temporal evolution of Attributes. **Only such structural timestamps can be used as** *timeproperty* **in Temporal Queries as mandated by [clause 4.11](9-tabcontext-information-management-framework.md#tabngsi-ld-temporal-query-language)** . -::: - -::: NO -NOTE 3: - -User-defined Properties whose value is a time value ( *Date, DateTime or Time* ) are defined as *Property* , not as *TemporalProperty* , and are serialized in NGSI-LD as shown in annex C, [clause C.6](15-annex-c-informative-examples-of-using-the-api.md#c.6tabdate-representation) . -::: - -Whenever a *TemporalProperty* value is unknown by a registered [Context Source]{.HTML_Keyboard}, the Property shall be omitted rather than sending an error response. - -## 4.9 NGSI-LD Query Language {#tabngsi-ld-query-language number="9.9"} - -The NGSI-LD Query Language shall be supported by implementations. It is intended to: - -::: B1plus -- filter out Entities by Attribute Values (target is the *value* member of a *Property*, see [Table 5.2.5‑1](10-tabapi-operation-definition.md#Table_5.2.5-1), or the *object* member of a Relationship, see [Table 5.2.6‑1](10-tabapi-operation-definition.md#Table_5.2.6-1)); -- filter out [Context Sources]{.HTML_Keyboard} by the values of properties that describe them, defined when [Context Sources]{.HTML_Keyboard} are registered (target is the name of a [Context Source]{.HTML_Keyboard} Property member of the CSourceRegistration, see Table 5.2.9-1). -- filter out [Snapshots]{.HTML_Keyboard} by the values of the Snapshot data type members, i.e. when filtering [Snapshots]{.HTML_Keyboard}, only the names of the members defined for Snapshot in [Table 5.2.43‑1](10-tabapi-operation-definition.md#Table_5.2.43-1) are allowed values for [AttrName]{.PL}. -::: - -In this clause, three string parameters are defined in order to fully specify an NGSI-LD Query: - -::: B1plus -- **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]{.HTML_Keyboard}. -::: - -**Optional** - -::: B1plus -- **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]{.HTML_Keyboard}. *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]](7-tabreferences.md#5)). - -The grammar that encodes the syntax of the **q** parameter, expressed in ABNF format [[12]](7-tabreferences.md#12), is the NGSI-LD Query Language. It is described below (it has been validated using [),]{.Hyperlink} and it shall be supported by implementations: - -``` json -Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm / -QueryTermAssoc)) -QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ; -(QueryTerm) -QueryTerm = Attribute -QueryTerm =/ Attribute Operator ComparableValue -QueryTerm =/ Attribute equal CompEqualityValue -QueryTerm =/ Attribute unequal CompEqualityValue -QueryTerm =/ Attribute patternOp RegExp -QueryTerm =/ Attribute notPatternOp RegExp -Attribute = LinkedEntityRelation -LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D ; -AttrName{LinkedEntityPath} -LinkedEntityRelation =/ ValuePath -LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B -LinkedEntityPath %x7D -;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath} -LinkedEntityPath =/ ValuePath -ValuePath = DottedPath *1(%x5B DottedPath %x5D) ; DottedPath -*1([DottedPath]) -DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName) -Operator = equal / unequal / greaterEq / greater / lessEq / less -ComparableValue = Number / quotedStr / dateTime / date / time -OtherValue = false / true -Value = ComparableValue / OtherValue -Range = ComparableValue dots ComparableValue -ValueList = Value 1*(%x2C Value) ; Value 1*(, Value) -CompEqualityValue = OtherValue / ValueList / Range / URI -equal = %x3D %x3D ; == -unequal = %x21 %x3D ; != -greater = %x3E ; > -greaterEq = %x3E %x3D ; >= -less = %x3C ; < -lessEq = %x3C %x3D ; <= -patternOp = %x7E %x3D ; ~= -notPatternOp = %x21 %x7E %x3D ; !~= -dots = %x2E %x2E ; .. -TermChar = unicodeNumber / unicodeLetter -TermChar =/ %x5F ; _ -AttrName = unicodeLetter *TermChar -EntityType = unicodeLetter *TermChar -quotedStr = String ; "*char" -andOp = %x3B ; ; -orOp = %x7C ; | -LogicalOp = andOp / orOp -``` - -::: B1plus -- [unicodeNumber]{.PL} is any Unicode character that has *Number* as a Category [[22]](7-tabreferences.md#22). With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \\p{N}. -- [unicodeLetter]{.PL} is any Unicode character that has *Letter* as a Category [[22]](7-tabreferences.md#22). With Unicode-capable regular expression (RegEx) parsers, such a character may be matched by \\p{L}. -- [Number]{.PL} shall be a number as mandated by the JSON Specification, following the ABNF Grammar, production rule named [number]{.PL}, section 6 of IETF RFC 8259 [[6]](7-tabreferences.md#6). -- [String]{.PL} shall be a text string as mandated by the JSON Specification, following the ABNF Grammar, production rule named [String]{.PL}, section 7 of IETF RFC 8259 [[6]](7-tabreferences.md#6). -- [char]{.PL} shall be a character as mandated by the JSON Specification, ABNF Grammar, production rule named [char]{.PL}, section 7 of IETF RFC 8259 [[6]](7-tabreferences.md#6). -- [false]{.PL} shall be conformant with the JSON ABNF Grammar, production rule named [false]{.PL}, section 3 of IETF RFC 8259 [[6]](7-tabreferences.md#6). It is intended to represent the Boolean value corresponding to *false*. -- [true]{.PL} shall be conformant with the JSON ABNF Grammar, production rule named [true]{.PL}, section 3 of IETF RFC 8259 [[6]](7-tabreferences.md#6). It is intended to represent the Boolean value corresponding to *true*. -- [RegExp]{.PL} shall be a regular expression as mandated by IEEE 1003.2™ [[11]](7-tabreferences.md#11). -- [dateTime]{.PL} shall be a *DateTime* value as mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values). -- [time]{.PL} shall be a *Time* value as mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values). -- [date]{.PL} shall be a *Date* value as mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values). -- [URI]{.PL} shall be a URI as mandated by IETF RFC 3986 [[5]](7-tabreferences.md#5) or an IRI as mandated by IETF RFC 3987 [[23]](7-tabreferences.md#23), appendix A, production rule named *URI*. -::: - -A **Query Term** (production rule [QueryTerm]{.PL}) defines a predicate which serves as a matching condition for Entities. The constituent parts of a Query Term are: - -::: B1plus -- an attribute path (production rule named [Attribute]{.PL}). -- an optional pair composed by an operator (production rule named [Operator]{.PL}) and a value (production rule named [Value]{.PL}). -::: - -The attribute path (production rule [Attribute]{.PL}) is a simple name [AttrName]{.PL}, optionally followed by a dot-separated list of more [AttrName]{.PL} (see later example 8), optionally followed by one trailing list of more dot-separated [AttrNames]{.PL} 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](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)) shall be issued. - -::: EX -EXAMPLE 0: - -[?q=temperature]{.HTML_Code} (checks for the existence of the attribute temperature). -::: - -::: EX -EXAMPLE 1: - -[?q=temperature==20]{.HTML_Code} . -::: - -::: EX -EXAMPLE 2: - -[?q=brandName!="Mercedes"]{.HTML_Code} . -::: - -::: EX -EXAMPLE 3: - -[?q=isParked=="urn:ngsi-ld:OffStreetParking:Downtown1"]{.HTML_Code} . -::: - -::: EX -EXAMPLE 4: - -A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in [clause 6.4.3.2](11-tabapi-http-binding.md#tabget) . The NGSI-LD query language string is conveyed by means of parameter **q** . -::: - -::: EX -EXAMPLE 5: - -[?q=isMonitoredBy]{.HTML_Code} (to query Entities that have the Attribute *isMonitoredBy* ). -::: - -Query Terms may be combined through logical operators that shall be supported by implementations as follows: - -::: B1plus -- The production rule [andOp]{.PL} 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]{.PL} 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. - -::: EX -EXAMPLE 6: - -[?q=((speed>50|rpm>3000);brandName=="Mercedes")]{.HTML_Code} -::: - -::: EX -EXAMPLE 7: - -[?q=(temperature>=20;temperature<=25)|capacity<=10]{.HTML_Code} -::: - -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: - -::: B1plus -- Every name in the list shall be expanded to a URI (Fully Qualified Name) as mandated by [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction). -- 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. -::: - -::: EX -EXAMPLE 8: - -[?q=temperature.observedAt>=2017-12-24T12:00:00Z]{.HTML_Code} -::: - -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]{.PL}), 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]](7-tabreferences.md#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. - -::: EX -EXAMPLE 9: - -[?q=address[city]=="Berlin"]{.HTML_Code} . The trailing path is [[city]]{.HTML_Code} . It is used to refer to a particular subitem within the value of the *address* *Property* , which is a complex JSON object representing a postal address. Refer to the following NGSI-LD Entity: - -``` json -{ -  "id": "urn:ngsi-ld:placedescription:123", -  "type": "PlaceDescription", -  "address": { -    "type": "Property", -    "value": { -      "city": "Berlin", -      "street": "Ulrich Strasse" -    } -  } -} -``` -::: - -::: EX -EXAMPLE 10: - -[?q=sensor.rawdata[airquality.particulate]==40]{.HTML_Code} . The trailing path is [[airquality.particulate].]{.HTML_Code} The *particulate Property* of the compound JSON object is targeted. Refer to the following NGSI-LD Entity: - -``` json -{ -  "id": "urn:ngsi-ld:particulatemeasurement:345", -  "type": "ParticulateMeasurement", -  "sensor": { -    "type": "Property", -    "value": 40, -    "rawdata": { -      "type": "Property", -      "value": { -        "airquality": { -          "particulate": 40, -          "PM20": 85 -        } -      } -    } -  } -} -``` -::: - -::: EX -EXAMPLE 11: - -[?q=parkingTickets[value]=="Overstay 60 minutes"&jsonKeys=parkingTickets]{.HTML_Code} . The trailing path is [parkingTickets]{.HTML_Code} . The [parkingTickets]{.HTML_Code} *Property* of the JSON object is targeted, but the target [value]{.HTML_Code} raw is JSON, and is not expanded to [ngsi-ld:hasValue]{.HTML_Code} using the core *\@context* . Refer to the following NGSI-LD Entity: - -``` json -{ -  "id": "urn:ngsi-ld:Car:6152s", -  "type": "Car", -  "parkingTickets": { -  "type": "JsonProperty", -  "json": { -         "id": "85a6cc52-0589-45f9", -         "value": "Overstay 60 minutes" -      } -  } -} -``` -::: - -::: EX -EXAMPLE 12: - -[?q=gender==Male&expandValues=gender]{.HTML_Code} . The trailing path is [gender]{.HTML_Code} . The *gender* *Property* of JSON object is targeted, but the target value is first expanded to a URI using the supplied *\@context* . Refer to the following NGSI-LD Entity: - -``` json -{ -  "id": "urn:ngsi-ld:Person:678", -  "type": "Person", -  "gender": { -    "type": "VocabProperty", -    "vocab": "Male", -    } -  }, -  @context": { -    "Male": "http://example.org/Male", -  } -} -``` -::: - -The filter can also apply to a *Property* or *Relationship* of an NGSI-LD Entity targeted by a (recursively) followed *Relationship,* for example as part of a linked entity retrieval [(clause 4.5.23](9-tabcontext-information-management-framework.md#tabngsi-ld-linked-entity-retrieval)). - -::: EX -EXAMPLE 13: - -[?q=sensor{humidity}==40]{.HTML_Code} . The trailing path is [sensor{humidity}]{.HTML_Code} . The query targets entities with a *sensor* *Relationship* and makes a sub-query on matching target objects which have the matching *humidity* Attribute. Refer to the following NGSI-LD Entities: - -``` json -{ -  "id": "urn:ngsi-ld:WeatherStation:123", -  "type": "WeatherStation", -  "sensor": { -    "type": "Relationship", -  "objectType": "Device", -    "object": "urn:ngsi-ld:Device:345" -  } -} -{ -  "id": "urn:ngsi-ld:Device:345", -  "type": "Device", -  "humidity": { -    "type": "Property", -    "value": 40 -  } -} -``` -::: - -As not knowing the Entity Type targeted by a *Relationship* could make the query significantly more expensive, a hint for the required Entity Type can be provided, so only such NGSI-LD Entities need to be considered. - -::: EX -EXAMPLE 14: - -[?q=sensor{Device:humidity}==40]{.HTML_Code} . The trailing path is [sensor{Device:humidity}]{.HTML_Code} . The query targets entities with a [sensor.entityType = "Device"]{.HTML_Code} within a *Relationship* and then makes a sub-query on matching target *objects* which have the matching *humidity* Attribute. The *entityType* hint results in a faster lookup. Refer to the following NGSI-LD Entities. - -``` json -{ -  "id": "urn:ngsi-ld:WeatherStation:123", -  "type": "WeatherStation", -  "sensor": { -    "type": "Relationship", -  "objectType": "Device", -    "object": "urn:ngsi-ld:Device:345" -  } -} -{ -  "id": "urn:ngsi-ld:Device:345", -  "type": "Device", -  "humidity": { -    "type": "Property", -    "value": 40 -  } -} -``` -::: - -If the target element corresponds to a *Relationship* or *ListRelationship*, the combination of such target element with any operator different than *equal* or *unequal* shall result in **not matching**. - -A **Query Term value** shall be any of the following (depending on the operator used): - -::: B1plus -- A literal value (string, number, date, etc.) (production rule named [Value]{.PL}). -- A range of values (production rule named [Range]{.PL}), specified as a minimum and a maximum value. -- A regular expression (production rule named [RegExp]{.PL}). -- A URI (production rule named [URI]{.PL}). -- A comma-separated list of literal values (production rule named [ValueList]{.PL}). -::: - -When comparing dates or times, the order relation considered shall be a temporal one. - -When it comes to comparing text strings, implementations: - -::: B1plus -- shall follow the recommendations defined by IETF RFC 8259 [[6]](7-tabreferences.md#6), section 8.3. -- should support the Unicode Collation Algorithm (UCA), as defined by [[13]](7-tabreferences.md#13). -::: - -URI comparison should be performed so that the number of false negatives is minimized, as recommended by IETF RFC 3986 [[5]](7-tabreferences.md#5), section 6. - -The semantics of the different logical operators used by Query Terms are described as follows and shall be supported by compliant implementations: - -::: B1plus -- **Existence** (only attribute is specified). A matching entity shall contain the target element. -- **Equal** operator (production rule named [equal]{.PL}). A matching Entity shall contain the target element and meet any of the following conditions: -::: - -::: B2plus -- The Query Term value, e.g. [color=="red"]{.HTML_Code}: -::: - -::: B3plus -- Is identical or equivalent to the target value (e.g. matches ["red"]{.HTML_Code}). -- Is included in the target value, if the latter is an array (e.g. matches [["blue","red","green"]]{.HTML_Code}). -::: - -::: B2plus -- If the Query Term value is a list of values (production rule named [ValueList]{.PL}), e.g. [color=="black", "red"]{.HTML_Code}: -::: - -::: B3plus -- The target value is identical or equivalent to any of the list values (e.g. matches ["red"]{.HTML_Code}). -- The target value includes any of the Query Term values, if the target value is an array (e.g. matches [["red","blue"]]{.HTML_Code}). -::: - -::: B2plus -- If the Query Term value is a range (production rule named [Range]{.PL}), e.g. [temperature==10..20]{.HTML_Code}: -::: - -::: B3plus -- The target value is in the interval between the minimum and maximum of the range (both included) (e.g. matches [15]{.HTML_Code}). -::: - -::: B2plus -- The Query Term value target element corresponds to a *LanguageProperty* and a natural language is specified e.g. [color[en]=="red"]{.HTML_Code}: -::: - -::: B3plus -- a match is found as the value of the key-value pair corresponding to the specified natural language of the *languageMap* (e.g. matches [{"fr": "rouge", "en": "red","de": "rot"}]{.HTML_Code} but not [{"fr": "red", "en": "black","de": "blue"}]{.HTML_Code}). -- a match is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the *languageMap* (e.g. matches [{"fr": ["chat", "rouge"], "en": ["red", "cat], "de": ["rote", "Katze"]}]{.HTML_Code} but not [{"fr": ["chat", "rouge"], "en" : ["coal", "black"],"de": ["blaue", "Engel"]}]{.HTML_Code}). -::: - -::: B2plus -- The Query Term value target element corresponds to a *LanguageProperty* and no natural language is specified e.g. [color[\*]=="red"]{.HTML_Code}: -::: - -::: B3plus -- any match is found in the values of the key-value pairs of the *languageMap* (e.g. matches [{"fr": "rouge", "en": "red", "de": "rote"}]{.HTML_Code}*.* -- a match is found as a single element of the array of values of the key-value pairs of the *languageMap* (e.g. matches [{"fr": "chat", "rouge"], "en": ["red", "cat"], "de": ["rote", "Katze"]}]{.HTML_Code}). -::: - -::: B2plus -- The Query Term value is a URI and the target element corresponds to a *Relationship*[, ]{.HTML_Keyboard}a*ListRelationship*or a*VocabProperty*, e.g. [color=="http://example/red"]{.HTML_Code}: -::: - -::: B3plus -- Is identical to the target value (e.g. matches ["http://example.com/red"]{.HTML_Code}). -- Is included in the target value, if the latter is an array (e.g. matches [["http://example.com/blue"," http://example.com/red"," http://example.com/green"]]{.HTML_Code}). -::: - -::: B2plus -- If the Query Term value target element corresponds to a *Relationship*[, ]{.HTML_Keyboard}a*ListRelationship*or a *VocabProperty* and is a list of URIs (production rule named *ValueList*), e.g. [color==" http://example/black","http://example/red"]{.HTML_Code}: -::: - -::: B3plus -- The target value is identical to any of the list values (e.g. matches ["http://example.com/red"]{.HTML_Code}). -- The target value includes any of the Query Term values, if the target value is an array (e.g. matches [["http://example.com/red", "http://example.com/blue"]]{.HTML_Code}). -::: - -::: B2plus -- If there is no equality between the target value data type and the Query Term value data type, then it shall be considered as not matching. -::: - -::: B1plus -- **Unequal** operator (production rule named [unequal]{.PL}). A matching entity shall contain the target element and meet any of the following conditions: -::: - -::: B2plus -- The Query Term value, e.g. [color!="red"]{.HTML_Code}: -::: - -::: B3plus -- Is neither identical nor equivalent to the target value (e.g. matches ["black"]{.HTML_Code}). -- Is not included in the target value, if the latter is an array (e.g. matches [["blue","black","green"]]{.HTML_Code}*,* but not [["blue","red","green"]]{.HTML_Code}). -::: - -::: B2plus -- If the Query Term value is a list of values (production rule named [ValueList]{.PL}), e.g. [color!= "black", "red":]{.HTML_Code} -::: - -::: B3plus -- The target value is neither identical nor equivalent to any of the list values (e.g. matches ["blue"]{.HTML_Code}). -- The target value does not include any of the list values, if the target value is an array (e.g. matches [["blue","yellow","green"]]{.HTML_Code}, but not [["blue","red","green"]]{.HTML_Code}). -::: - -::: B2plus -- If the Query Term value is a range (production rule named [Range]{.PL}), e.g. [temperature!=10..20]{.HTML_Code}: -::: - -::: B3plus -- The target value is not in the interval between the minimum and the maximum (both included) (e.g. matches 9). -::: - -::: B2plus -- The Query Term value target element corresponds to a *LanguageProperty* and a natural language is specified e.g. [color[en]!="red"]{.HTML_Code}: -::: - -::: B3plus -- No matching value is found as the value of the specified language key of a *languageMap* where a language filter is specified. (e.g. matches [{"fr": "noir", "en": "black","de": "schwarz"}]{.HTML_Code} but not [{"fr": "rouge", "en" : "red","de": "rot"})]{.HTML_Code}. -- No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the *languageMap* (e.g. matches [{"fr": ["chat", "rouge"], "en": ["coal", "black"], "de": ["blaue", "Engel"]}]{.HTML_Code} but not [{"fr": ["rouge", "noir"], "en" : ["red", "black"],"de": ["rot", "schwarz"]}]{.HTML_Code}). -::: - -::: B2plus -- The Query Term value target element corresponds to a *LanguageProperty* and no language filter is specified e.g. [color[\*]!="red"]{.HTML_Code}: -::: - -::: B3plus -- No matching value is found in any of the values of the key-value pairs of a *languageMap* (e.g. matches [{"fr": "noir", "en": "black","de": "schwarz"}]{.HTML_Code}, but not [{"fr": "rouge", "en": "red","de": "rot"}]{.HTML_Code}). -- No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the *languageMap* (e.g. matches [{"fr": ["chat", "rouge"], "en": ["coal", "black"], "de": ["blaue", "Engel"]}]{.HTML_Code} but not [{"fr": ["rouge", "noir"], "en": ["red", "black"],"de": ["rot", "schwartz"]}]{.HTML_Code}). -::: - -::: B2plus -- The Query Term value is a URI and the target element corresponds to a *Relationship*[, ]{.HTML_Keyboard}a*ListRelationship*ora *VocabProperty*, e.g. [color!="http://example.com/red"]{.HTML_Code}: -::: - -::: B3plus -- Is not identical to the target value (e.g. matches ["http://example.com/black"]{.HTML_Code}). -- Is not included in the target value, if the latter is an array (e.g. matches [["http://example.com/blue", "http://example.com/black", "http://example.com/green"]]{.HTML_Code}*,* but not [["http://example.com/blue", "http://example.com/red", "http://example.com/green"]]{.HTML_Code})*.* -::: - -::: B2plus -- If the Query Term value target element corresponds to a *Relationship*[, ]{.HTML_Keyboard}a*ListRelationship*or a *VocabProperty* and is a list of URIs e.g. [color!="http://example.com/black", " http://example.com/red"]{.HTML_Code}: -::: - -::: B3plus -- The target value is not identical to any of the list values (e.g. matches ["http://example.com/blue"]{.HTML_Code}). -- The target value does not include any of the list values, if the target value is an array (e.g. matches [["http://example.com/blue", "http://example.com/yellow", "http://example.com/green"]]{.HTML_Code}, but not [["http://example.com/blue", "http://example.com/red", "http://example.com/green"]]{.HTML_Code}). -::: - -::: B2plus -- If the data type of the target value and the data type of the Query Term value are different, then they shall be considered unequal. -::: - -::: B1plus -- **Greater than** operator (production rule named [greater]{.PL}). For an entity to match, it shall contain the target element and the target value has to be strictly greater than the Query Term value: -::: - -::: B2plus -- If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching. -::: - -::: B1plus -- **Less than** operator (production rule named [less]{.PL}). For an entity to match, it shall contain the target element and the target value shall be strictly less than the value: -::: - -::: B2plus -- If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching. -::: - -::: B1plus -- **Greater or equal than** (production rule named [greaterEq]{.PL}). A matching entity shall meet any of the *Greater than* or the *Equal* conditions for single values. -- **Less or equal than** (production rule named [lessEq]{.PL}). A matching entity shall meet any of the *Less than* or the *Equal* conditions for single values. -- **Match pattern** (production rule named [patternOp]{.PL}). A matching entity shall contain the target element and the target value shall be in the L(R) of the regular pattern specified by the Query Term: -::: - -::: B2plus -- If the target value data type is different than *String* then it shall be considered as not matching. -::: - -::: B1plus -- **Do not match pattern** (production rule named *notPatternOp*). A matching entity shall contain the target element and the target value shall not be in the L(R) of the regular pattern specified by the Query Term: -::: - -::: B2plus -- If the target value data type is different than *String* then it shall be considered as not matching. -::: - -## 4.10 NGSI-LD Geoquery Language {#tabngsi-ld-geoquery-language number="9.10"} - -The NGSI-LD Geoquery language shall be supported by implementations. It is intended to define predicates which allow testing whether a specific topological spatial relationship exists between a pair of geometries: a target geometry and a reference geometry. The target geometry represents a geospatial Property of an Entity, typically, the location of the Entity. - -A total of four parameters are defined in order to fully specify an NGSI-LD Geoquery: - -::: B1plus -- **georel**, to express the desired geospatial relationship; -- **geometry**, to express the type of the reference geometry; -- **coordinates**, to express the reference geometry; -- **geoproperty**, to express the target geometry of an Entity. This parameter is optional, *location* is the default. -::: - -The following grammar defines the syntax for the geospatial relationships (parameter name **georel**): - -``` json -andOp = %x3B ; ; -equal = %x3D %x3D ; == -georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel -/ equalsRel / disjointRel -nearRel = nearOp andOp distance equal PositiveNumber ; -near;max(min)Distance==x (in meters) -distance = "maxDistance" / "minDistance" -nearOp = "near" -withinRel = "within" -containsRel = "contains" -intersectsRel = "intersects" -equalsRel = "equals" -disjointRel = "disjoint" -overlapsRel = "overlaps" -``` - -[PositiveNumber]{.PL} shall be a non-zero positive number as mandated by the JSON Specification. Thus, it shall follow the ABNF Grammar, production rule named [Number]{.PL}, section 6 of IETF RFC 8259 [[6]](7-tabreferences.md#6), excluding the 'minus' symbol and excluding the number 0. - -Reference geometries shall be specified by: - -::: B1plus -- A geometry type (parameter name **geometry**) as defined by the GeoJSON specification (IETF RFC 7946 [[8]](7-tabreferences.md#8), section 1.4), except *GeometryCollection*. -- A coordinates (parameter name **coordinates**) element which shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [[8]](7-tabreferences.md#8), section 3.1.1. -::: - -Target geometry, i.e. the target Entity's *GeoProperty* to which the geoquery is to be applied, can be specified by an extra parameter named **geoproperty**. The *GeoProperty's* name shall be specified as short hand name and not a fully qualified one, because, when the query language is used, an *\@context* properly defining all the terms (as per [clause 5.5.7](10-tabapi-operation-definition.md#tabterm-to-uri-expansion-or-compaction)) shall be issued. If no *geoproperty* is specified, the geoquery is applied to the default *Property* *location* (see [clause 4.7.1](9-tabcontext-information-management-framework.md#tabgeojson-geometries)). - -Note that proper URL encoding shall be used by HTTP binding API clients when using these examples. - -::: EX -EXAMPLE 1: - -[?georel=near;maxDistance==2000]{.HTML_Code} - -``` json -&geometry=Point -&coordinates=[8,40] -&geoproperty=observationSpace -``` -::: - -::: EX -EXAMPLE 2: - -[?georel=within]{.HTML_Code} - -``` json -&geometry=Polygon -&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0], -[100.0,0.0]]] -&geoproperty=location -``` -::: - -::: EX -EXAMPLE 3: - -A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in [clause 6.4.3.2](11-tabapi-http-binding.md#tabget) . - -``` json -&geometry=Point -&coordinates=[8,40] -``` -::: - -The semantics of the different geospatial relationships defined above is as follows, and shall be supported by compliant implementations: - -::: B1plus -- **near** statement (production rule named [nearRel]{.PL}): -::: - -::: B2plus -- [maxDistance]{.PL} modifier. For an entity to match it has to be within the buffer geometric object (as defined by [[14]](7-tabreferences.md#14)) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named [PositiveNumber]{.PL}). -- [minDistance]{.PL} modifier. For an entity to match it has to be disjoint with the buffer geometric object (as defined by [[14]](7-tabreferences.md#14)) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named [PositiveNumber]{.PL}). -::: - -::: B1plus -- **equals** relationship (production rule named [equalsRel]{.PL}). For an entity to match, the target geometry shall be equal, as specified by [[14]](7-tabreferences.md#14), to the reference geometry. -- **disjoint** relationship (production rule named [disjointRel]{.PL}). For an entity to match, the target geometry shall be disjoint, as specified by [[14]](7-tabreferences.md#14), to the reference geometry. -- **intersects** relationship (production rule named [intersectsRel]{.PL}). For an entity to match, the target geometry shall intersect, as specified by [[14]](7-tabreferences.md#14), with the reference geometry. -- **within** relationship (production rule named *withinRel*). For an entity to match, the target geometry shall be within, as specified by [[14]](7-tabreferences.md#14), the reference geometry. -- **contains** relationship (production rule named [containsRel]{.PL}). For an entity to match, the target geometry shall contain, as specified by [[14]](7-tabreferences.md#14), the reference geometry. -- **overlaps** relationship (production rule named [overlapsRel]{.PL}). For an entity to match, the target geometry shall overlap, as specified by [[14]](7-tabreferences.md#14), the reference geometry. -::: - -When resolving geo-queries, Entities which do not convey the target *GeoProperty* of the query shall be considered as non-matching. - -## 4.11 NGSI-LD Temporal Query Language {#tabngsi-ld-temporal-query-language number="9.11"} - -The NGSI-LD Temporal Query language shall be supported by implementations. It is intended to define predicates which allow testing whether Temporal Properties of NGSI-LD Entities, Properties and Relationships, are within certain temporal constraints. In particular it can be used to request historic Property values and Relationships that were valid within the specified timeframe. - -The following grammar defines the syntax that shall be supported: - -``` json -timerel = beforeRel / afterRel / betweenRel -beforeRel = "before" -afterRel = "after" -betweenRel = "between" -``` - -The points in time for comparison are defined as follows: - -::: B1plus -- A **timeAt** parameter, which shall represent the comparison point for the *before* and *after* relation and the starting point for the *between* relation. It shall be represented as *DateTime* (mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)). -- An **endTimeAt** parameter, which is only used for the *between* relation and shall represent the end point for comparison. It shall be represented as *DateTime* (mandated by [clause 4.6.3](9-tabcontext-information-management-framework.md#tabsupported-data-types-for-values)). -::: - -The Temporal Property (see [clause 4.8](9-tabcontext-information-management-framework.md#tabtemporal-properties)) to which the temporal query is to be applied can be specified by **timeproperty**. If no *timeproperty* is specified, the temporal query is applied to the default Temporal Property *observedAt*. - -::: EX -EXAMPLE 1: - -[?timerel=before &timeAt=2017-12-13T14:20:00Z]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -[?timerel=between &timeAt=2017-12-13T14:20:00Z &endTimeAt=2017-12-13T14:40:00Z &timeproperty=modifiedAt]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -Temporal query encoded as HTTP Query String, note that this is HTTP binding specific, to be used via GET method, as defined in [clause 6.18.3.2](11-tabapi-http-binding.md#tabget-8) . - -``` json -&timeproperty=observedAt -&timeAt=2017-12-13T14:20:00Z -``` -::: - -The semantics of the different temporal relations defined above is as follows, and shall be supported by compliant implementations: - -::: B1plus -- **before** relationship (production rule named [beforeRel]{.PL}). For a Temporal Property to match, the value of the specified Temporal Property (or *observedAt* as default) has to be before the time specified by *timeAt*. The specified value is used as an exclusive bound in the Temporal Query; -- **after** relationship (production rule named [afterRel]{.PL}). For a Temporal Property to match, the value of the specified Temporal Property (or *observedAt* as default) has to be after the time specified by *timeAt*. The specified value is used as an inclusive bound in the Temporal Query; -- **between** relationship (production rule named [betweenRel]{.PL}). For a Temporal Property to match, the value of the specified Temporal Property (or *observedAt* as default) has to be after the time specified by *timeAt* and before the time specified by *endTimeAt*. In the Temporal Query, the value specified for the lower bound of the range is inclusive and the value specified for the upper bound of the range is exclusive. -::: - -When resolving temporal queries, Entities which do not convey the target Temporal Property of the query shall be considered as non-matching. - -## 4.12 NGSI-LD Pagination {#tabngsi-ld-pagination number="9.12"} - -NGSI-LD operations can potentially return a result set including a large number of NGSI-LD Elements, so that pagination of query results shall be supported by compliant implementations. - -The list of operations that incur this behaviour is as follows: - -::: B1plus -- Query Entities [(clause 5.7.2](10-tabapi-operation-definition.md#tabquery-entities)). -- Query Subscriptions [(clause 5.8.4](10-tabapi-operation-definition.md#tabquery-subscriptions)). -- Query [Context Source Registrations]{.HTML_Keyboard} [(clause 5.10.2](10-tabapi-operation-definition.md#tabquery-context-source-registrations)). -- Query [Context Source Registration]{.HTML_Keyboard} Subscriptions [(clause 5.11.5](10-tabapi-operation-definition.md#tabquery-context-source-registration-subscriptions)). -- Query [Temporal Evolution of Entities]{.HTML_Keyboard} [(clause 5.7.4](10-tabapi-operation-definition.md#tabquery-temporal-evolution-of-entities)). -::: - -Nonetheless, the NGSI-LD API is agnostic about specific pagination mechanisms and only defines the behaviour that shall be observed by NGSI-LD Systems. - -For each operation above, NGSI-LD Systems shall: - -::: B1plus -- provide a mechanism to iterate through the NGSI-LD Elements of a result set without exhausting NGSI-LD Client or Broker resources; -- provide a mechanism to flag NGSI-LD Clients when there are remaining NGSI-LD Elements to be traversed as part of a result set; -- allow NGSI-LD Clients specifying a limit (page size), as a parameter of API operations, to the number of NGSI-LD Elements (at a maximum) retrieved by the implementation for each pagination iteration; -- define a **default limit** (default page size) to the number of NGSI-LD Elements retrieved per pagination iteration; -- allow NGSI-LD Clients iterating forwards and backwards through a result set. -::: - -NGSI-LD implementations should: - -::: B1plus -- avoid Denial of Service attacks or other potential security risks, by defining a hard limit to the size of generated response payload body while paginating. For instance, certain queries can be rejected by issuing an error of type *TooManyResults*. -::: - -NGSI-LD implementations may: - -::: B1plus -- warn NGSI-LD Clients when result sets become invalid due to dynamic changes in NGSI-LD Elements (additions, deletions) occurred while iterating over pages. -::: - -The concrete realization of the features described above might depend on each API binding. Nonetheless, NGSI-LD Systems shall implement pagination features as mandated by the present clause, for any API binding. - -## 4.13 Counting the Number of Results {#tabcounting-the-number-of-results number="9.13"} - -Given that NGSI-LD Query operations can potentially return a result set including a large number of NGSI-LD Elements and that pagination of query results shall be supported (see [clause 4.12](9-tabcontext-information-management-framework.md#tabngsi-ld-pagination)), compliant implementations shall also support a mechanism for relaying to the client the number of expected resulting elements, when a query is executed. - -A specific field (e.g. a custom header in the response in case of HTTP binding, see [clause 6.3.13](11-tabapi-http-binding.md#tabcounting-number-of-results)) shall be returned within the response of a query, whenever this is requested by the client. - -Mechanisms for limiting the number of returned NGSI-LD Elements are independent of the counting mechanism, so that, potentially, a client can issue a query that limits to zero the number of desired results but asks for the count to be present. - -This is useful for client-side planning and fine-tuning of subsequent queries and their parameters. - -## 4.14 Supporting Multiple Tenants {#tabsupporting-multiple-tenants number="9.14"} - -The concept of a [Tenant]{.HTML_Keyboard} is that a user or group of users utilizes a single instance of an NGSI-LD system ([Context Source]{.HTML_Keyboard} or [Context Broker]{.HTML_Keyboard}) in isolation from other users or groups of users of the same instance, which are considered to be different [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}. Thus a multi-tenant NGSI-LD system is a system where a single software instance is used by different users or groups of users, the [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}, where any information related to one [Tenant]{.HTML_Keyboard} (e.g. Entities, Subscriptions, [Context Source Registrations]{.HTML_Keyboard}) are only visible to users of the same [Tenant]{.HTML_Keyboard}, but not to users of a different [Tenant]{.HTML_Keyboard}. Typically, multi-tenancy is used together with an access control mechanism, enforcing the isolation of [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}, however access control and other security-related aspects are out-of-scope of the present document. - -The NGSI-LD API optionally enables multi-tenant systems. To support this, [Tenant]{.HTML_Keyboard} information can be optionally specified in NGSI-LD API operations. The operation then only applies to the targeted [Tenant]{.HTML_Keyboard}. As all information of one [Tenant]{.HTML_Keyboard} is isolated from other [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}, the NGSI-LD API operations for managing, retrieving and subscribing to entity information, but also any context source related operations only apply to the information of the specified [Tenant]{.HTML_Keyboard} in isolation and never have any effect on the information of other [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard}. - -As the support and use of [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard} is optional, any operation not explicitly specifying a [Tenant]{.HTML_Keyboard} targets a default [Tenant]{.HTML_Keyboard}, which always exists. NGSI-LD systems not supporting multiple [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard} should raise an error of type *NoMultiTenantSupport* if a [Tenant]{.HTML_Keyboard} is specified. To enable [Context Sources]{.HTML_Keyboard} to be part of tenant-based distributed or federated systems, [Tenant]{.HTML_Keyboard} information can optionally be specified in [Context Source Registrations]{.HTML_Keyboard}. When contacting the respective [Context Sources]{.HTML_Keyboard}, the [Tenant]{.HTML_Keyboard} information from the [Context Source Registration]{.HTML_Keyboard} has to be used. If no [Tenant]{.HTML_Keyboard} information is present in the [Context Source Registration]{.HTML_Keyboard}, no [Tenant]{.HTML_Keyboard} information is to be used and thus the default [Tenant]{.HTML_Keyboard} is targeted on the registered [Context Source]{.HTML_Keyboard}. This enables integrating [Context Sources]{.HTML_Keyboard} not supporting multi-tenancy in a distributed system with a [Tenant]{.HTML_Keyboard}-based [Context Broker]{.HTML_Keyboard} or integrating local [Tenant]{.HTML_Keyboard}[s]{.HTML_Keyboard} in a federated system using a different [Tenant]{.HTML_Keyboard}. - -## 4.15 NGSI-LD Language Filter {#tabngsi-ld-language-filter number="9.15"} - -The NGSI-LD Language Filter shall be supported by implementations. It is intended to form a mechanism which allows just one matching string value of *LanguageProperties* of NGSI-LD Entities to be converted to an NGSI-LD Property, where the value will be a string for the specified natural language. - -The following grammar defines the syntax that shall be supported by the filter: - -::: B1 -[ lang = langtag]{.HTML_Code} -::: - -Where the langtag is defined according to the rules as mandated by IETF RFC 5646 [[28]](7-tabreferences.md#28), and IETF RFC 3282 [[29]](7-tabreferences.md#29). If the [Context Broker]{.HTML_Keyboard} cannot serve any matching language, it shall default to any supported language. This behaviour can be triggered by specifying [lang="\*"]{.HTML_Code}in the filter (see example 3). - -In any case, the attribute in question shall be augmented with an additional non-reified subproperty *lang* indicating the actual language returned. - -::: EX -EXAMPLE 1: - -Specified natural language - return LanguageProperties as strings in English only. -::: - -::: EX -[lang="en"]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -Multiple natural languages with no ranked preference - return LanguageProperties as strings in either Swiss French or French. -::: - -::: EX -[lang="fr-CH,fr"]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -Wildcard - return LanguageProperties as a string in any supported language. -::: - -::: EX -[ lang="\*"]{.HTML_Code} -::: - -::: EX -EXAMPLE 4: - -Quality value ranking - return all LanguageProperties as a string in Swiss French or French with no ranked preference, fallback to English as a second choice and finally fallback to any other supported language. -::: - -::: EX -[lang="fr-CH,fr;q=0.9,en;q=0.8,\*;q=0.5"]{.HTML_Code} -::: - -## 4.16 Supporting Multiple Entity Types {#tabsupporting-multiple-entity-types number="9.16"} - -From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any Entity are supported. An Entity is uniquely identified by its id, so whenever information is provided for an Entity with a given id, it is considered part of the same Entity, regardless of the Entity Type(s) specified. To avoid unexpected behaviour, Entity Types can be implicitly added by all operations that update or append attributes. There is no operation to remove Entity Types from an Entity. The philosophy here is to assume that an Entity always had all Entity Types, but possibly not all Entity Types have previously been known in the system. The only option to remove an Entity Type is to delete the Entity and re-create it with the same id. Alternatively, a batch upsert with 'replace' update mode can be used, as described in [clause 5.6.8](10-tabapi-operation-definition.md#tabbatch-entity-creation-or-update-upsert). - -## 4.17 NGSI-LD Entity Type Selection Language {#tabngsi-ld-entity-type-selection-language number="9.17"} - -The NGSI-LD Entity Type Selection Language shall be supported by implementations. It is intended to select only those Entities that have the specified Entity Type(s), possibly among others. Entity Types are specified as a disjunction of elements, where each element can either directly be an Entity Type or a conjunction of multiple Entity Types. The logical operators are the same as in the NGSI-LD Query Language specified in [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). As a disjunction of Entity Types can also be seen as a list, and to be compatible with previous versions of the NGSI-LD API, a comma can be used as an alternative representation of the *or* operator. For logical *and* grouping parenthesis are needed. - -``` json -EntityTypes = OrEntityType *(orOp OrEntityType) ; OrEntityType|OrEntityType -OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType) -OrEntityType = EntityType                        ; EntityType -andOp = %x3B                        ; ; -orOp = %x7C / %x2C                                                  ; |  , -``` - -[EntityType]{.PL} is either a valid name as specified in [clause 4.6.2](9-tabcontext-information-management-framework.md#tabsupported-names) or a URI. - -::: EX -EXAMPLE 1: - -Entities of type Building or House: -::: - -::: EX -[Building|House]{.HTML_Code} -::: - -::: EX -[Building,House]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -Entities of type Home and Vehicle: -::: - -::: EX -[(Home;Vehicle)]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -Entities of type (Home and Vehicle) or Motorhome: -::: - -::: EX -[(Home;Vehicle)|Motorhome]{.HTML_Code} -::: - -::: EX -[(Home;Vehicle),Motorhome]{.HTML_Code} -::: - -::: NO -NOTE: - -The special characters [","]{.HTML_Code} , [";"]{.HTML_Code} , ["("]{.HTML_Code} and [")"]{.HTML_Code} used in the Entity Type Selection Language are allowed characters in URIs. The use of short names is recommended. -::: - -## 4.18 NGSI-LD Scopes {#tabngsi-ld-scopes number="9.18"} - -An NGSI-LD Scope enables putting Entities into a hierarchical structure and restrict results of queries and notifications accordingly. The hierarchical structure is user-defined, e.g. according to (logical) location or organization. The use of Scopes is optional and an Entity can be assigned to one or more Scopes at the same time. The Scope is represented as a special *scope* Property that is non-reified in the normalized Entity representation and reified in the temporal representation of an Entity. In the latter case, it is restricted to having the non-reified Temporal Properties *createdAt, modifiedAt* and *deletedAt* as sub-Properties. There shall at most be one instance of the *scope* property per Entity. In case multiple representations of the same Entity have to be merged, e.g. when combining the results of distributed queries, the values of *scope* are merged. The value of *scope* is represented as a JSON array in case there is more than one Scope. For the Temporal Evolution a given Scope is considered valid from the time it has been set until the time it has been explicitly removed by an update or delete operation (for an example see [annex C](15-annex-c-informative-examples-of-using-the-api.md#annex-c-informative-examples-of-using-the-api), [clause C.5.16](15-annex-c-informative-examples-of-using-the-api.md#c.5.16tabtemporal-scope-queries)). - -The grammar that encodes the syntax of the Scope is expressed in ABNF format [[12]](7-tabreferences.md#12). It is described below (it has been validated using [),]{.Hyperlink} and it shall be supported by implementations. The special string "urn:ngsi-ld:null" (i.e. the NGSI-LD Null) shall be only used and only appear in case of deleted scopes. - -``` json -Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)              ; [/] ScopeLevel *(/ScopeLevel) -Scope =/ "urn:ngsi-ld:null"                               ; the literal string "urn:ngsi-ld:null" -ScopeLevel = unicodeLetter *ScopeLevelChar -ScopeLevelChar = unicodeNumber / unicodeLetter -ScopeLevelChar =/ %x5F                                    ; _ -``` - -::: EX -EXAMPLE 1: - -[/Madrid]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -[Madrid]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -[/Madrid/Gardens/ParqueNorte]{.HTML_Code} -::: - -::: EX -EXAMPLE 4: - -[/CompanyA/OrganizationB/UnitC]{.HTML_Code} -::: - -## 4.19 NGSI-LD Scope Query Language {#tabngsi-ld-scope-query-language number="9.19"} - -The NGSI-LD Scope Query Language shall be supported by implementations. It is intended to select only those Entities that are within the specified Scope(s). Scopes are specified as a disjunction of elements, where each element can either directly be a Scope or a conjunction of multiple Scopes. The ["+"]{.HTML_Code} can be used as a wildcard to match a single scope level within a Scope. The ["#"]{.HTML_Code} that can be added at the end of a Scope specification serves as a wildcard, which matches the given scope and the whole hierarchy of scopes below. The ["/#"]{.HTML_Code} matches any non-empty scope, i.e. only explicitly specified scopes. The logical operators are the same as in the NGSI-LD Query Language specified in [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language). As a disjunction of Scopes can also be seen as a list, a comma can be used as an alternative representation of the *or* operator. For logical *and* grouping parenthesis are needed. - -``` json -ScopesQ = OrScopeQ *(orOp OrScopeQ) ; OrScopeQ|OrScopeQ -ScopesQ =/ %x2F %23 ; / # -OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29             ; (ScopeQ;ScopeQ) -OrScopeQ =/ ScopeQ *1(%x2F %23)                          ; ScopeQ / # -andOp = %x3B                        ; ; -orOp = %x7C / %x2C                                                  ; |  , -ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel) -ScopeQLevel = unicodeLetter *ScopeQLevelChar -ScopeQLevel =/ %x2B ; +  -ScopeQLevelChar = unicodeNumber / unicodeLetter -ScopeQLevelChar =/ %x5F                                             ; _ -``` - -::: EX -EXAMPLE 1: - -Scope /Madrid: -::: - -::: EX -[/Madrid]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -Scope /Madrid/Gardens and the whole scope tree below: - -``` json -/Madrid/Gardens/#, -/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur -``` -::: - -::: EX -EXAMPLE 3: - -Scopes /Madrid/Gardens/ParqueNorte and /Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first scope level and ParqueNorte as third scope level: -::: - -::: EX -[/Madrid/+/ParqueNorte]{.HTML_Code} -::: - -::: EX -EXAMPLE 4: - -Scope /Madrid/Districts and /CompanyA: -::: - -::: EX -[(/Madrid/Districts;/CompanyA)]{.HTML_Code} -::: - -::: EX -EXAMPLE 5: - -Scope (/Madrid/Districts and /CompanyA) or /CompanyB: -::: - -::: EX -[(/Madrid/Districts;/CompanyA)|CompanyB]{.HTML_Code} -::: - -::: EX -[(/Madrid/Districts;/CompanyA),CompanyB]{.HTML_Code} -::: - -## 4.20 NGSI-LD Distributed Operation names {#tabngsi-ld-distributed-operation-names number="9.20"} - -When registering [Context Sources]{.HTML_Keyboard} (see [clause 5.2.9](10-tabapi-operation-definition.md#tabcsourceregistration)), the registrant NGSI-LD interface endpoint may optionally offer a subset of NGSI-LD operations which it accepts. [Table 4.20‑1](9-tabcontext-information-management-framework.md#Table_4.20-1) defines a list of names for each of these operations. - -::: {#Table_4.20-1 .TH} -Table 4.20-1: Names of implemented Operations -::: - -::: TAL -+-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ -| Operation name | Implements | | -+===============================================+===============================+=============================================================================+ -| Context Information Provision | createEntity | 5.6.1 Create Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateEntity | 5.6.2 Update Attributes | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | appendAttrs | 5.6.3 Append Attributes | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateAttrs | 5.6.4 Partial Attribute update | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteAttrs | 5.6.5 Delete Attribute | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteEntity | 5.6.6 Delete Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | createBatch | 5.6.7 Batch Entity Creation | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | upsertBatch | 5.6.8 Batch Entity Creation or Update (Upsert) | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateBatch | 5.6.9 Batch Entity Update | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteBatch | 5.6.10 Batch Entity Delete | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | upsertTemporal | 5.6.11 Create or Update Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | appendAttrsTemporal | 5.6.12 Add Attributes to Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteAttrsTemporal | 5.6.13 Delete Attributes from Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateAttrInstanceTemporal | 5.6.14 Partial Update Attribute Instance in Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteAttrInstanceTemporal | 5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteTemporal | 5.6.16 Delete Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | mergeEntity | 5.6.17 Merge Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | replaceEntity | 5.6.18 Replace Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | replaceAttrs | 5.6.19 Replace Attribute | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | mergeBatch | 5.6.20 Batch Entity Merge | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | purgeEntity | 5.6.21 Purge Entities | -+-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ -| Context Information Consumption | retrieveEntity | 5.7.1 Retrieve Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | queryEntity | 5.7.2 Query Entities (excluding batch entity queries) | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | queryBatch | 5.7.2 Query Entities (batch entity queries only) | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveTemporal | 5.7.3 Retrieve Temporal Evolution of an Entity | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | queryTemporal | 5.7.4 Query Temporal Evolution of Entities | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveEntityTypes | 5.7.5 Retrieve Available Entity Types | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveEntityTypeDetails | 5.7.6 Retrieve Details of Available Entity Types | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveEntityTypeInfo | 5.7.7 Retrieve Available Entity Type Information | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveAttrTypes | 5.7.8 Retrieve Available Attributes | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveAttrTypeDetails | 5.7.9 Retrieve Details of Available Attributes | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveAttrTypeInfo | 5.7.10 Retrieve Available Attribute Information | -+-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ -| Context Information Subscription | createSubscription | 5.8.1 Create Subscription | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateSubscription | 5.8.2 Update Subscription | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveSubscription | 5.8.3 Retrieve Subscription | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | querySubscription | 5.8.4 Query Subscription | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteSubscription | 5.8.5 Delete Subscription | -+-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ -| Support operations for distributed operations | retrieveEntityMap | 5.14.1 Retrieve EntityMap | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | updateEntityMap | 5.14.2 Update EntityMap | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | deleteEntityMap | 5.14.3 Delete EntityMap | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | createEntityMapQueryEntity | 5.14.4 Create EntityMap for Query Entities | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | createEntityMapQueryTemporal | 5.14.5 Create EntityMap for Query Temporal Evolution of Entities | -| +-------------------------------+-----------------------------------------------------------------------------+ -| | retrieveContextSourceIdentity | 5.15.1 Retrieve Context Source Identity Information | -+-----------------------------------------------+-------------------------------+-----------------------------------------------------------------------------+ -::: - -In addition to these individual operations, a series of names for common groups of operations have also been defined. [Table 4.20‑2](9-tabcontext-information-management-framework.md#Table_4.20-2) defines a list of names for each of these operation groups. - -::: {#Table_4.20-2 .TH} -Table 4.20-2: Named Operation Groups -::: - -::: TAL -+-------------------------------------+-------------------------------------+ -| Operation Group name | Implements | -+=====================================+=====================================+ -| federationOps | - retrieveEntity | -| | - queryEntity | -| | - queryBatch | -| | - retrieveEntityTypes | -| | - retrieveEntityTypeDetails | -| | - retrieveEntityTypeInfo | -| | - retrieveAttrTypes | -| | - retrieveAttrTypeDetails | -| | - retrieveAttrTypeInfo | -| | - createSubscription | -| | - updateSubscription | -| | - retrieveSubscription | -| | - querySubscription | -| | - deleteSubscription | -| | - retrieveEntityMap | -| | - updateEntityMap | -| | - deleteEntityMap | -| | - createEntityMapQueryEntity | -| | - retrieveContextSourceIdentity | -+-------------------------------------+-------------------------------------+ -| associationOps | -+-------------------------------------+-------------------------------------+ -| updateOps | - updateEntity | -| | - updateAttrs | -| | - replaceEntity | -| | - replaceAttrs | -+-------------------------------------+-------------------------------------+ -| retrieveOps | - retrieveEntity | -| | - queryEntity | -+-------------------------------------+-------------------------------------+ -| redirectionOps | - createEntity | -| | - updateEntity | -| | - appendAttrs | -| | - updateAttrs | -| | - deleteAttrs | -| | - deleteEntity | -| | - mergeEntity | -| | - replaceEntity | -| | - replaceAttrs | -| | - retrieveEntity | -| | - queryEntity | -| | - purgeEntity | -| | - retrieveEntityTypes | -| | - retrieveEntityTypeDetails | -| | - retrieveEntityTypeInfo | -| | - retrieveAttrTypes | -| | - retrieveAttrTypeDetails | -| | - retrieveAttrTypeInfo | -| | - retrieveEntityMap | -| | - updateEntityMap | -| | - deleteEntityMap | -| | - createEntityMapQueryEntity | -| | - retrieveContextSourceIdentity | -+-------------------------------------+-------------------------------------+ -::: - -If no specific subset of operations is defined for a [Context Source Registration]{.HTML_Keyboard}, the default set of operations matches the group defined as ["federationOps"]{.HTML_Code}. - -## 4.21 NGSI-LD Attribute Projection Language {#tabngsi-ld-attribute-projection-language number="9.21"} - -The NGSI-LD Attribute Projection Language shall be supported by implementations for projection parameters (e.g. *pick* and *omit*). Its aim is to specify the Attributes to be retrieved within an Entity (or associated [Linked Entities]{.HTML_Keyboard} when Linked Entity Retrieval is used). Projected Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or in the case of Linked Entity Retrieval, a Relationship name followed by an Attribute name within the [Linked Entity.]{.HTML_Keyboard} Since a disjunction of Attributes is a list, either a comma or a pipe character can be used as alternative representations of the *or* operator. In the following, ABNF grammar for NGSI-LD Attribute Projection Language is given. - -``` json -orOp = %x7C / %x2C                                                  ; |  , -ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm) -LinkedEntityTerm  = %x7B ProjectionTerm %x7D ; {ProjectionTerm} -``` - -See [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) for the definition of [AttrName]{.PL}. - -::: EX -EXAMPLE 1: - -[?pick=temperature]{.HTML_Code} -::: - -::: EX -EXAMPLE 2: - -[?pick=temperature,humidity]{.HTML_Code} -::: - -::: EX -EXAMPLE 3: - -[?pick=observation{temperature,humidity}]{.HTML_Code} -::: - -## 4.22 Transient Storage of Entities and Attributes {#tabtransient-storage-of-entities-and-attributes number="9.22"} - -In some cases, it is desirable to create an Entity (or Attribute) which is only expected to be stored for a defined period of time. Thereafter such an Entity (or Attribute) should be removed, and can be safely deleted from the context via an automatic garbage collection process. - -In this regard NGSI-LD defines the following system Property of type *TemporalProperty* that shall be supported by implementations: - -::: B1plus -- **expiresAt** is defined as the system temporal Property at which a certain Entity, Property or Relationship shall become invalid and may be automatically removed from the Context Broker. For example, an Alert Entity was created to last for 24 hours and should be removed after this period of time. -::: - -It should be noted that clean-up processes will only run periodically, and will be dependent upon the Context Broker implementation, therefore final deletion will always lag the *expiresAt* timestamp to a certain extent. Furthermore, *expiresAt* only applies to the local storage, i.e. the Entity or Attribute is to be deleted locally, but not on other Context Sources or Context Broker hosting such Entity information, where no *expiresAt* timestamp is present. Thus *expiresAt* is not considered to be intrinsic to the Entity or Attribute, but only applies to the storage of the Entity or Attribute respectively. As it pertains to a system function (the deletion from storage after the expiration time), it is considered to be a system attribute. - -## 4.23 Entity Ordering {#tabentity-ordering number="9.23"} - -### 4.23.1 Introduction {#tabintroduction-14 number="9.23.1"} - -When a Context Consumer queries for Entities retrieved from a single context broker, it shall be possible to request that the array of Entities returned are ordered according to the values held within an Entity Attribute. Context Broker implementations shall interpret such requests and return the array of Entities sorted accordingly. - -For each Attribute name listed, one of four types of sort order can be specified: - -::: B1plus -- Sort in ascending order by **target value** or **target object** -- Sort in descending order by **target value** or **target object** -- Sort by distance in ascending order from a specified GeoJSON geometry -- Sort by distance in descending order from a specified GeoJSON geometry -::: - -When sorting by ascending or descending order, the preferred sort order for numbers and datetimes is trivial, however for strings the default collation order shall be defined as using ICU "root" collation order (["und-x-icu"]{.HTML_Code}) which returns a reasonable language-agnostic sort order (see IETF RFC 6067 [[36]](7-tabreferences.md#36)). - -Sort by distance shall be limited to GeoProperties, and shall be defined as calculating spherical distance using the Haversine formula. - -Sort ordering is **never applied** to distributed operations, and the defined sort ordering strategy may depend on implementation specific configurations. - -### 4.23.2 Datatype Comparison Order {#tabdatatype-comparison-order number="9.23.2"} - -When sorting by value, and the values of Attributes are of mixed datatypes, the following comparison order (*null* values last), shall be implicitly applied: - -::: B1plus -- Numbers -- Strings -- Object -- Array -- Boolean -- *Time* -- *Date* -- *DateTime* -- Null -- Attribute does not exist -::: - -Additionally, when sorting by distance, the following comparison order, shall be applied: - -::: B1plus -- Attribute is a GeoProperty -- Attribute is not a GeoProperty - sorted by value as shown above. -::: - -### 4.23.3 NGSI-LD Entity Ordering Language {#tabngsi-ld-entity-ordering-language number="9.23.3"} - -The NGSI-LD Entity Ordering Language shall be supported by implementations for the order parameter (i.e. *orderBy*). Its aim is to specify the Attributes to be used when ordering an Array of Entities retrieved. Ordering Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or an Attribute name followed by a direction (either ascending or descending, where ascending shall be the default if not supplied). The comma character shall be used to separate the elements to be used for ordering which shall be applied sequentially. - -In the following, ABNF grammar for NGSI-LD Entity Ordering Language is given. - -``` json -thenOp = %x2C                                                   ; , -directionOp ::= asc | desc | dist-asc| -dist-desc -OrderingTerm = AttrName *1(DirectionTerm) *(thenOp OrderingTerm) -DirectionTerm = %x3B directionOp. ; ; -``` - -See [clause 4.9](9-tabcontext-information-management-framework.md#tabngsi-ld-query-language) for the definition of [AttrName]{.PL}. - -::: EX -EXAMPLE 1: - -[?orderBy=name ]{.HTML_Code} - applies sort ordering to rank Entities in ascending order using the value of the [name]{.HTML_Code} Attribute. -::: - -::: EX -EXAMPLE 2: - -[?orderBy=name,age ]{.HTML_Code} - applies sort ordering to rank Entities in ascending order using the value of the [name]{.HTML_Code} Attribute and thereafter where multiple Entities have the same [name]{.HTML_Code} , by ascending order using the [age]{.HTML_Code} Attribute. -::: - -::: EX -EXAMPLE 3: - -[?orderBy=name,age;desc ]{.HTML_Code} - applies sort ordering to rank Entities in ascending order using the value of the [name]{.HTML_Code} Attribute and thereafter where multiple Entities have the same [name]{.HTML_Code} , by descending order using the value of [age]{.HTML_Code} Attribute. -::: - -::: EX -EXAMPLE 4: - -[?orderBy=address[city] ]{.HTML_Code} - applies sort ordering using a sub-item within a Property Value defined as a complex JSON object. The trailing path is [[city]]{.HTML_Code} . It is used to refer to a particular subitem within the value of the *address* *Property* . -::: - -::: EX -EXAMPLE 5: - -[?orderBy=name.observedAt ]{.HTML_Code} - applies sort ordering based on 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. -::: - -When sorting data using a specific ICU collation order as defined by IETF RFC 6067 [[36]](7-tabreferences.md#36), the collation element (parameter name **collation**) shall represent the preferred ordering. - -::: EX -EXAMPLE 6: - -[?orderBy=name&collation=und-u-ks-identic ]{.HTML_Code} - applies sort ordering to rank Entities in ascending order using the case insensitive value of the [name]{.HTML_Code} Attribute. -::: - -::: EX -EXAMPLE 7: - -[?orderBy=name&collation=de-u-co-phonebk ]{.HTML_Code} - applies sort ordering to rank Entities in ascending order using the value of the [name]{.HTML_Code} Attribute and sorted according to German phonebook collation ordering. -::: - -For sort by distance, the coordinates element (parameter name **orderFrom**) shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [[8]](7-tabreferences.md#8), section 3.1.2. - -::: EX -EXAMPLE 8: - -[?orderBy=location;dist-asc&orderFrom=[8,40] ]{.HTML_Code} - applies sort ordering to rank Entities in ascending distance from a Point with respect to the *location* *GeoProperty* . -::: - -::: EX -EXAMPLE 9: - -[?orderBy=location;dist-desc&orderFrom=[8,40] ]{.HTML_Code} - applies sort ordering to rank Entities in descending distance from a Point with respect to the *location* *GeoProperty* . -::: - -::: EX -EXAMPLE 10: - -[?orderBy=location;dist-asc]{.HTML_Code} - -``` json -&orderFrom=[[8,40],[9,42],[9,45],[8,40]] -&orderGeometry=LineString -``` -::: diff --git a/API/0--1.html b/API/0--1.html deleted file mode 100644 index f0e3f6b761c38e0a247bb903b1baf13b1f8581ce..0000000000000000000000000000000000000000 --- a/API/0--1.html +++ /dev/null @@ -1,2515 +0,0 @@ - - - - - - - -consolidated - - - - - - - - - - - - -
-
-

ETSI GS CIM 009V1.8.29(2025-05)

-
-
-

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.

-
-

Group Specification

-
-

Reference

-

RGS/CIM-009v181

-

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:<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 atwww.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 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 2024.

-

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 27

-

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 32

-

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 40

-

4.3.6.3 Proxied Registrations 41

-

4.3.6.4 Limiting Cascading Distributed Operations 41

-

4.3.6.5 Extra information to provide when contacting Context Source 41

-

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 42

-

4.3.6.8 Backwards compatibility of Context Source payloads 43

-

4.3.7 Snapshots 45

-

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 49

-

4.5.3 NGSI-LD Relationship Representations 51

-

4.5.3.1 Introduction 51

-

4.5.3.2 Normalized NGSI-LD Relationship 51

-

4.5.3.3 Concise NGSI-LD Relationship 53

-

4.5.4 Simplified Representation 54

-

4.5.5 Multi-Attribute Support 58

-

4.5.5.1 Introduction 58

-

4.5.5.2 Processing of Conflicting Transient Entities 59

-

4.5.5.3 Processing of Conflicting Attributes 59

-

4.5.6 Temporal Representation of an Entity 60

-

4.5.7 Temporal Representation of a Property 60

-

4.5.8 Temporal Representation of a Relationship 60

-

4.5.9 Simplified temporal representation of an Entity 60

-

4.5.10 Entity Type List Representation 64

-

4.5.11 Detailed Entity Type List Representation 64

-

4.5.12 Entity Type Information Representation 64

-

4.5.13 Attribute List Representation 64

-

4.5.14 Detailed Attribute List Representation 65

-

4.5.15 Attribute Information Representation 65

-

4.5.16 GeoJSON Representation of Entities 65

-

4.5.16.0 Foreword 65

-

4.5.16.1 Top-level “geometry” field selection algorithm 66

-

4.5.16.2 GeoJSON Representation of an individual Entity 66

-

4.5.16.3 GeoJSON Representation of Multiple Entities 66

-

4.5.17 Simplified GeoJSON Representation of Entities 67

-

4.5.17.0 Foreword 67

-

4.5.17.1 Simplified GeoJSON Representation of an individual Entity 67

-

4.5.17.2 Simplified GeoJSON Representation of multiple Entities 68

-

4.5.18 NGSI-LD LanguageProperty Representations 68

-

4.5.18.1 Introduction 68

-

4.5.18.2 Normalized NGSI-LD LanguageProperty 68

-

4.5.18.3 Concise NGSI-LD LanguageProperty 69

-

4.5.19 Aggregated temporal representation of an Entity 69

-

4.5.19.0 Foreword 69

-

4.5.19.1 Supported behaviours for aggregation functions 70

-

4.5.20 NGSI-LD VocabProperty Representations 72

-

4.5.20.1 Introduction 72

-

4.5.20.2 Normalized NGSI-LD VocabProperty 72

-

4.5.20.3 Concise NGSI-LD VocabProperty 72

-

4.5.21 NGSI-LD ListProperty Representations 73

-

4.5.21.1 Introduction 73

-

4.5.21.2 Normalized NGSI-LD ListProperty 73

-

4.5.21.3 Concise NGSI-LD ListProperty 74

-

4.5.22 NGSI-LD ListRelationship Representations 74

-

4.5.22.1 Introduction 74

-

4.5.22.2 Normalized NGSI-LD ListRelationship 74

-

4.5.22.3 Concise NGSI-LD ListRelationship 75

-

4.5.23 NGSI-LD Linked Entity Retrieval 76

-

4.5.23.1 Introduction 76

-

4.5.23.2 Inline Linked Entity Representation 76

-

4.5.23.3 Flattened Linked Entity Representation 76

-

4.5.24 NGSI-LD JsonProperty Representations 76

-

4.5.24.1 Introduction 76

-

4.5.24.2 Normalized NGSI-LD JsonProperty 76

-

4.5.24.3 Concise NGSI-LD JsonProperty 77

-

4.5.25 NGSI-LD EntityMap Representation 77

-

4.6 Data Representation Restrictions 78

-

4.6.1 Supported text encodings 78

-

4.6.2 Supported names 78

-

4.6.3 Supported data types for Values 78

-

4.6.4 Supported Content 79

-

4.6.5 Supported data types for LanguageMaps 80

-

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

-

4.7 Geospatial Properties 80

-

4.7.1 GeoJSON Geometries 80

-

4.7.2 Representation of GeoJSON Geometries in JSON-LD 81

-

4.7.3 Concise NGSI-LD GeoProperty 81

-

4.8 Temporal Properties 81

-

4.9 NGSI-LD Query Language 82

-

4.10 NGSI-LD Geoquery Language 90

-

4.11 NGSI-LD Temporal Query Language 92

-

4.12 NGSI-LD Pagination 93

-

4.13 Counting the Number of Results 93

-

4.14 Supporting Multiple Tenants 94

-

4.15 NGSI-LD Language Filter 94

-

4.16 Supporting Multiple Entity Types 95

-

4.17 NGSI-LD Entity Type Selection Language 95

-

4.18 NGSI-LD Scopes 95

-

4.19 NGSI-LD Scope Query Language 96

-

4.20 NGSI-LD Distributed Operation names 97

-

4.21 NGSI-LD Attribute Projection Language 99

-

4.22 Transient Storage of Entities and Attributes 99

-

4.23 Entity Ordering 99

-

4.23.1 Introduction 99

-

4.23.2 Datatype Comparison Order 100

-

4.23.3 NGSI-LD Entity Ordering Language 100

-

5 API Operation Definition 101

-

5.1 Introduction 101

-

5.2 Data Types 101

-

5.2.1 Introduction 101

-

5.2.2 Common members 102

-

5.2.3 @context 102

-

5.2.4 Entity 102

-

5.2.5 Property 103

-

5.2.6 Relationship 105

-

5.2.7 GeoProperty 107

-

5.2.8 EntityInfo 109

-

5.2.9 CSourceRegistration 109

-

5.2.10 RegistrationInfo 113

-

5.2.11 TimeInterval 113

-

5.2.12 Subscription 113

-

5.2.13 GeoQuery 116

-

5.2.14 NotificationParams 116

-

5.2.14.1 NotificationParams data type definition 116

-

5.2.14.2 Output only members 117

-

5.2.15 Endpoint 118

-

5.2.16 BatchOperationResult 119

-

5.2.17 BatchEntityError 119

-

5.2.18 UpdateResult 120

-

5.2.19 NotUpdatedDetails 120

-

5.2.20 EntityTemporal 120

-

5.2.21 TemporalQuery 120

-

5.2.22 KeyValuePair 121

-

5.2.23 Query 122

-

5.2.24 EntityTypeList 124

-

5.2.25 EntityType 124

-

5.2.26 EntityTypeInfo 124

-

5.2.27 AttributeList 125

-

5.2.28 Attribute 125

-

5.2.29 Feature 126

-

5.2.30 FeatureCollection 126

-

5.2.31 FeatureProperties 127

-

5.2.32 LanguageProperty 127

-

5.2.33 EntitySelector 129

-

5.2.34 RegistrationManagementInfo 129

-

5.2.35 VocabProperty 131

-

5.2.36 ListProperty 132

-

5.2.37 ListRelationship 134

-

5.2.38 JsonProperty 137

-

5.2.39 EntityMap 139

-

5.2.40 Context Source Identity 140

-

5.2.41 Snapshot 140

-

5.2.42 ExecutionResultDetails 142

-

5.2.43 OrderingParams 143

-

5.2.44 AggregationParams 143

-

5.3 Notification data types 144

-

5.3.1 Notification 144

-

5.3.2 CSourceNotification 145

-

5.3.3 TriggerReasonEnumeration 145

-

5.3.4 SnapshotNotification 145

-

5.4 NGSI-LD Fragments 146

-

5.5 Common Behaviours 147

-

5.5.1 Introduction 147

-

5.5.2 Error types 147

-

5.5.3 Error response payload body 148

-

5.5.4 General NGSI-LD validation 148

-

5.5.5 Default @context assignment 149

-

5.5.6 Operation execution and generic error handling 149

-

5.5.7 Term to URI expansion or compaction 149

-

5.5.8 Partial Update Patch Behaviour 150

-

5.5.9 Pagination Behaviour 152

-

5.5.9.1 General Pagination Behaviour 152

-

5.5.9.2 Pagination option using limit and offset 153

-

5.5.9.3 Pagination with Entity maps 153

-

5.5.10 Multi-Tenant Behaviour 153

-

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

-

5.5.11.0 Foreword 153

-

5.5.11.1 Batch Entity Creation case 154

-

5.5.11.2 Batch Entity Creation or Update (Upsert) case 154

-

5.5.11.3 Batch Entity Update case 154

-

5.5.11.4 Batch Entity Delete case 154

-

5.5.11.5 Batch Entity Merge case 154

-

5.5.12 Merge Patch Behaviour 155

-

5.5.13 Limiting operations to local scope 156

-

5.5.14 Distributed Transactional Behaviour 156

-

5.5.15 Snapshot Behaviour 157

-

5.6 Context Information Provision 157

-

5.6.1 Create Entity 157

-

5.6.1.1 Description 157

-

5.6.1.2 Use case diagram 158

-

5.6.1.3 Input data 158

-

5.6.1.4 Behaviour 158

-

5.6.1.5 Output data 159

-

5.6.2 Update Attributes 159

-

5.6.2.1 Description 159

-

5.6.2.2 Use case diagram 159

-

5.6.2.3 Input data 159

-

5.6.2.4 Behaviour 159

-

5.6.2.5 Output data 160

-

5.6.3 Append Attributes 161

-

5.6.3.1 Description 161

-

5.6.3.2 Use case diagram 161

-

5.6.3.3 Input data 161

-

5.6.3.4 Behaviour 161

-

5.6.3.5 Output data 162

-

5.6.4 Partial Attribute update 162

-

5.6.4.1 Description 162

-

5.6.4.2 Use case diagram 163

-

5.6.4.3 Input data 163

-

5.6.4.4 Behaviour 163

-

5.6.4.5 Output data 164

-

5.6.5 Delete Attribute 164

-

5.6.5.1 Description 164

-

5.6.5.2 Use case diagram 164

-

5.6.5.3 Input data 165

-

5.6.5.4 Behaviour 165

-

5.6.5.5 Output data 166

-

5.6.6 Delete Entity 166

-

5.6.6.1 Description 166

-

5.6.6.2 Use case diagram 166

-

5.6.6.3 Input data 166

-

5.6.6.4 Behaviour 166

-

5.6.6.5 Output data 167

-

5.6.7 Batch Entity Creation 167

-

5.6.7.1 Description 167

-

5.6.7.2 Use case diagram 167

-

5.6.7.3 Input data 167

-

5.6.7.4 Behaviour 167

-

5.6.7.5 Output data 168

-

5.6.8 Batch Entity Creation or Update (Upsert) 168

-

5.6.8.1 Description 168

-

5.6.8.2 Use case diagram 169

-

5.6.8.3 Input data 169

-

5.6.8.4 Behaviour 169

-

5.6.8.5 Output data 171

-

5.6.9 Batch Entity Update 171

-

5.6.9.1 Description 171

-

5.6.9.2 Use case diagram 171

-

5.6.9.3 Input data 171

-

5.6.9.4 Behaviour 171

-

5.6.9.5 Output data 173

-

5.6.10 Batch Entity Delete 173

-

5.6.10.1 Description 173

-

5.6.10.2 Use case diagram 173

-

5.6.10.3 Input data 173

-

5.6.10.4 Behaviour 173

-

5.6.10.5 Output data 174

-

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

-

5.6.11.1 Description 174

-

5.6.11.2 Use case diagram 175

-

5.6.11.3 Input data 175

-

5.6.11.4 Behaviour 175

-

5.6.11.5 Output data 176

-

5.6.12 Add Attributes to Temporal Evolution of an Entity 176

-

5.6.12.1 Description 176

-

5.6.12.2 Use case diagram 176

-

5.6.12.3 Input data 176

-

5.6.12.4 Behaviour 177

-

5.6.12.5 Output data 177

-

5.6.13 Delete Attribute from Temporal Evolution of an Entity 177

-

5.6.13.1 Description 177

-

5.6.13.2 Use case diagram 177

-

5.6.13.3 Input data 178

-

5.6.13.4 Behaviour 178

-

5.6.13.5 Output data 179

-

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity 179

-

5.6.14.1 Description 179

-

5.6.14.2 Use case diagram 179

-

5.6.14.3 Input data 180

-

5.6.14.4 Behaviour 180

-

5.6.14.5 Output data 180

-

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity 181

-

5.6.15.1 Description 181

-

5.6.15.2 Use case diagram 181

-

5.6.15.3 Input data 181

-

5.6.15.4 Behaviour 181

-

5.6.15.5 Output data 182

-

5.6.16 Delete Temporal Evolution of an Entity 182

-

5.6.16.1 Description 182

-

5.6.16.2 Use case diagram 182

-

5.6.16.3 Input data 183

-

5.6.16.4 Behaviour 183

-

5.6.16.5 Output data 183

-

5.6.17 Merge Entity 184

-

5.6.17.1 Description 184

-

5.6.17.2 Use case diagram 184

-

5.6.17.3 Input data 184

-

5.6.17.4 Behaviour 184

-

5.6.17.5 Output data 186

-

5.6.18 Replace Entity 186

-

5.6.18.1 Description 186

-

5.6.18.2 Use case diagram 186

-

5.6.18.3 Input data 187

-

5.6.18.4 Behaviour 187

-

5.6.18.5 Output data 188

-

5.6.19 Replace Attribute 188

-

5.6.19.1 Description 188

-

5.6.19.2 Use case diagram 188

-

5.6.19.3 Input data 188

-

5.6.19.4 Behaviour 188

-

5.6.19.5 Output data 189

-

5.6.20 Batch Entity Merge 189

-

5.6.20.1 Description 189

-

5.6.20.2 Use case diagram 189

-

5.6.20.3 Input data 190

-

5.6.20.4 Behaviour 190

-

5.6.20.5 Output data 191

-

5.6.21 Purge Entities 191

-

5.6.21.1 Description 191

-

5.6.21.2 Use case diagram 191

-

5.6.21.3 Input data 192

-

5.6.21.4 Behaviour 192

-

5.6.21.5 Output data 193

-

5.7 Context Information Consumption 193

-

5.7.1 Retrieve Entity 193

-

5.7.1.1 Description 193

-

5.7.1.2 Use case diagram 193

-

5.7.1.3 Input data 194

-

5.7.1.4 Behaviour 195

-

5.7.1.5 Output data 196

-

5.7.2 Query Entities 197

-

5.7.2.1 Description 197

-

5.7.2.2 Use case diagram 197

-

5.7.2.3 Input data 197

-

5.7.2.4 Behaviour 198

-

5.7.2.5 Output data 201

-

5.7.3 Retrieve Temporal Evolution of an Entity 202

-

5.7.3.1 Description 202

-

5.7.3.2 Use case diagram 202

-

5.7.3.3 Input data 202

-

5.7.3.4 Behaviour 203

-

5.7.3.5 Output data 204

-

5.7.4 Query Temporal Evolution of Entities 204

-

5.7.4.1 Description 204

-

5.7.4.2 Use case diagram 204

-

5.7.4.3 Input data 204

-

5.7.4.4 Behaviour 205

-

5.7.4.5 Output Data 208

-

5.7.5 Retrieve Available Entity Types 208

-

5.7.5.1 Description 208

-

5.7.5.2 Use case diagram 208

-

5.7.5.3 Input data 209

-

5.7.5.4 Behaviour 209

-

5.7.5.5 Output data 209

-

5.7.6 Retrieve Details of Available Entity Types 209

-

5.7.6.1 Description 209

-

5.7.6.2 Use case diagram 209

-

5.7.6.3 Input data 210

-

5.7.6.4 Behaviour 210

-

5.7.6.5 Output data 210

-

5.7.7 Retrieve Available Entity Type Information 210

-

5.7.7.1 Description 210

-

5.7.7.2 Use case diagram 210

-

5.7.7.3 Input data 211

-

5.7.7.4 Behaviour 211

-

5.7.7.5 Output data 211

-

5.7.8 Retrieve Available Attributes 211

-

5.7.8.1 Description 211

-

5.7.8.2 Use case diagram 211

-

5.7.8.3 Input data 212

-

5.7.8.4 Behaviour 212

-

5.7.8.5 Output data 212

-

5.7.9 Retrieve Details of Available Attributes 212

-

5.7.9.1 Description 212

-

5.7.9.2 Use case diagram 212

-

5.7.9.3 Input data 213

-

5.7.9.4 Behaviour 213

-

5.7.9.5 Output data 213

-

5.7.10 Retrieve Available Attribute Information 213

-

5.7.10.1 Description 213

-

5.7.10.2 Use case diagram 213

-

5.7.10.3 Input data 214

-

5.7.10.4 Behaviour 214

-

5.7.10.5 Output data 214

-

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

-

5.8 Context Information Subscription 215

-

5.8.1 Create Subscription 215

-

5.8.1.1 Description 215

-

5.8.1.2 Use case diagram 215

-

5.8.1.3 Input data 215

-

5.8.1.4 Behaviour 215

-

5.8.1.5 Output data 217

-

5.8.2 Update Subscription 217

-

5.8.2.1 Description 217

-

5.8.2.2 Use case diagram 217

-

5.8.2.3 Input data 217

-

5.8.2.4 Behaviour 218

-

5.8.2.5 Output data 218

-

5.8.3 Retrieve Subscription 218

-

5.8.3.1 Description 218

-

5.8.3.2 Use case diagram 218

-

5.8.3.3 Input data 219

-

5.8.3.4 Behaviour 219

-

5.8.3.5 Output data 219

-

5.8.4 Query Subscriptions 219

-

5.8.4.1 Description 219

-

5.8.4.2 Use case diagram 219

-

5.8.4.3 Input data 220

-

5.8.4.4 Behaviour 220

-

5.8.4.5 Output data 220

-

5.8.5 Delete Subscription 220

-

5.8.5.1 Description 220

-

5.8.5.2 Use case diagram 220

-

5.8.5.3 Input data 221

-

5.8.5.4 Behaviour 221

-

5.8.5.5 Output data 221

-

5.8.6 Notification behaviour 221

-

5.9 Context Source Registration 223

-

5.9.1 Introduction 223

-

5.9.2 Register Context Source 223

-

5.9.2.1 Description 223

-

5.9.2.2 Use case diagram 224

-

5.9.2.3 Input data 224

-

5.9.2.4 Behaviour 224

-

5.9.2.5 Output data 225

-

5.9.3 Update Context Source Registration 225

-

5.9.3.1 Description 225

-

5.9.3.2 Use case diagram 225

-

5.9.3.3 Input data 225

-

5.9.3.4 Behaviour 226

-

5.9.3.5 Output data 226

-

5.9.4 Delete Context Source Registration 226

-

5.9.4.1 Description 226

-

5.9.4.2 Use case diagram 226

-

5.9.4.3 Input data 227

-

5.9.4.4 Behaviour 227

-

5.9.4.5 Output data 227

-

5.10 Context Source Discovery 227

-

5.10.1 Retrieve Context Source Registration 227

-

5.10.1.1 Description 227

-

5.10.1.2 Use case diagram 227

-

5.10.1.3 Input data 228

-

5.10.1.4 Behaviour 228

-

5.10.1.5 Output data 228

-

5.10.2 Query Context Source Registrations 228

-

5.10.2.1 Description 228

-

5.10.2.2 Use case diagram 229

-

5.10.2.3 Input data 229

-

5.10.2.4 Behaviour 230

-

5.10.2.5 Output data 231

-

5.11 Context Source Registration Subscription 231

-

5.11.1 Introduction 231

-

5.11.2 Create Context Source Registration Subscription 231

-

5.11.2.1 Description 231

-

5.11.2.2 Use case diagram 231

-

5.11.2.3 Input data 231

-

5.11.2.4 Behaviour 232

-

5.11.2.5 Output data 232

-

5.11.3 Update Context Source Registration Subscription 233

-

5.11.3.1 Description 233

-

5.11.3.2 Use case diagram 233

-

5.11.3.3 Input data 233

-

5.11.3.4 Behaviour 233

-

5.11.3.5 Output data 233

-

5.11.4 Retrieve Context Source Registration Subscription 233

-

5.11.4.1 Description 233

-

5.11.4.2 Use case diagram 234

-

5.11.4.3 Input data 234

-

5.11.4.4 Behaviour 234

-

5.11.4.5 Output data 234

-

5.11.5 Query Context Source Registration Subscriptions 234

-

5.11.5.1 Description 234

-

5.11.5.2 Use case diagram 234

-

5.11.5.3 Input data 235

-

5.11.5.4 Behaviour 235

-

5.11.5.5 Output data 235

-

5.11.6 Delete Context Source Registration Subscription 235

-

5.11.6.1 Description 235

-

5.11.6.2 Use case diagram 235

-

5.11.6.3 Input data 236

-

5.11.6.4 Behaviour 236

-

5.11.6.5 Output data 236

-

5.11.7 Notification behaviour 236

-

5.12 Matching Context Source Registrations 237

-

5.13 Storing, Managing and Serving @contexts 238

-

5.13.1 Introduction 238

-

5.13.2 Add @context 239

-

5.13.2.1 Description 239

-

5.13.2.2 Use case diagram 239

-

5.13.2.3 Input data 239

-

5.13.2.4 Behaviour 240

-

5.13.2.5 Output data 240

-

5.13.3 List @contexts 240

-

5.13.3.1 Description 240

-

5.13.3.2 Use case diagram 240

-

5.13.3.3 Input data 240

-

5.13.3.4 Behaviour 241

-

5.13.3.5 Output data 241

-

5.13.4 Serve @context 241

-

5.13.4.1 Description 241

-

5.13.4.2 Use case diagram 241

-

5.13.4.3 Input data 242

-

5.13.4.4 Behaviour 242

-

5.13.4.5 Output data 242

-

5.13.5 Delete and Reload @context 242

-

5.13.5.1 Description 242

-

5.13.5.2 Use case diagram 242

-

5.13.5.3 Input data 243

-

5.13.5.4 Behaviour 243

-

5.13.5.5 Output data 243

-

5.14 Context Source Entity Mapping 243

-

5.14.1 Retrieve EntityMap 243

-

5.14.1.1 Description 243

-

5.14.1.2 Use case diagram 243

-

5.14.1.3 Input data 244

-

5.14.1.4 Behaviour 244

-

5.14.1.5 Output data 244

-

5.14.2 Update EntityMap 244

-

5.14.2.1 Description 244

-

5.14.2.2 Use case diagram 244

-

5.14.2.3 Input data 245

-

5.14.2.4 Behaviour 245

-

5.14.2.5 Output data 245

-

5.14.3 Delete EntityMap 245

-

5.14.3.1 Description 245

-

5.14.3.2 Use case diagram 245

-

5.14.3.3 Input data 246

-

5.14.3.4 Behaviour 246

-

5.14.3.5 Output data 246

-

5.14.4 Create EntityMap for Query Entities 246

-

5.14.4.1 Description 246

-

5.14.4.2 Use case diagram 246

-

5.14.4.3 Input data 247

-

5.14.4.4 Behaviour 248

-

5.14.4.5 Output data 249

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities 250

-

5.14.5.1 Description 250

-

5.14.5.2 Use case diagram 250

-

5.14.5.3 Input data 250

-

5.14.5.4 Behaviour 251

-

5.7.4.5 Output Data 253

-

5.15 Context Source Identity Information 253

-

5.15.1 Retrieve Context Source Identity Information 253

-

5.15.1.1 Description 253

-

5.15.1.2 Use case diagram 253

-

5.15.1.3 Input data 254

-

5.15.1.4 Behaviour 254

-

5.15.1.5 Output data 254

-

5.16 Snapshot Functionality 254

-

5.16.1 Create Snapshot 254

-

5.16.1.1 Description 254

-

5.16.1.2 Use case diagram 254

-

5.16.1.3 Input data 255

-

5.16.1.4 Behaviour 255

-

5.16.1.5 Output data 256

-

5.16.2 Clone Snapshot 256

-

5.16.2.1 Description 256

-

5.16.2.2 Use case diagram 256

-

5.16.2.3 Input data 256

-

5.16.2.4 Behaviour 256

-

5.16.2.5 Output data 257

-

5.16.3 Retrieve Snapshot Status 257

-

5.16.3.1 Description 257

-

5.16.3.2 Use case diagram 257

-

5.16.3.3 Input data 258

-

5.16.3.4 Behaviour 258

-

5.16.3.5 Output data 258

-

5.16.4 Update Snapshot Status 258

-

5.16.4.1 Description 258

-

5.16.4.2 Use case diagram 258

-

5.16.4.3 Input data 258

-

5.16.4.4 Behaviour 259

-

5.16.4.5 Output data 259

-

A JSON-LD object representing the Snapshot status as mandated by .16.5 Delete Snapshot 259

-

5.16.5.1 Description 259

-

5.16.5.2 Use case diagram 259

-

5.16.5.3 Input data 259

-

5.16.5.4 Behaviour 259

-

5.16.5.5 Output data 260

-

5.16.6 Snapshot status notification behaviour 260

-

5.16.7 Purge Snapshots 260

-

5.16.7.1 Description 260

-

5.16.7.2 Use case diagram 260

-

5.16.7.3 Input data 261

-

5.16.7.4 Behaviour 261

-

5.16.7.5 Output data 261

-

6 API HTTP Binding 261

-

6.1 Introduction 261

-

6.2 Global Definitions and Resource Structure 261

-

6.3 Common Behaviours 265

-

6.3.1 Introduction 265

-

6.3.2 Error Types 265

-

6.3.3 Reporting errors 266

-

6.3.4 HTTP request preconditions 266

-

6.3.5 JSON-LD @context resolution 267

-

6.3.6 HTTP response common requirements 267

-

6.3.7 Representation of Entities 268

-

6.3.8 Notification behaviour 269

-

6.3.9 Csource Notification behaviour 270

-

6.3.10 Pagination behaviour 270

-

6.3.11 Including system Attributes 272

-

6.3.12 Simplified or aggregated temporal representation of Entities 272

-

6.3.13 Counting number of results 273

-

6.3.14 Tenant specification 273

-

6.3.15 GeoJSON representation of spatially bound entities 273

-

6.3.16 Expiration time for cached @contexts 273

-

6.3.17 Distributed Operations Caching and Timeout Behaviour 274

-

6.3.18 Limiting Distributed Operations 274

-

6.3.19 Extra information to provide when contacting Context Source 275

-

6.3.20 Invalid parameters 275

-

6.3.21 Optional profile information regarding versioning and datatype conformance 275

-

6.3.22 Snapshot specification 276

-

6.4 Resource: entities/ 276

-

6.4.1 Description 276

-

6.4.2 Resource definition 276

-

6.4.3 Resource methods 276

-

6.4.3.1 POST 276

-

6.4.3.2 GET 277

-

6.4.3.3 DELETE 281

-

6.5 Resource: entities/{entityId} 283

-

6.5.1 Description 283

-

6.5.2 Resource definition 283

-

6.5.3 Resource methods 284

-

6.5.3.1 GET 284

-

6.5.3.2 DELETE 286

-

6.5.3.3 PUT 287

-

6.5.3.4 PATCH 289

-

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

-

6.6.1 Description 290

-

6.6.2 Resource definition 290

-

6.6.3 Resource methods 291

-

6.6.3.1 POST 291

-

6.6.3.2 PATCH 292

-

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

-

6.7.1 Description 293

-

6.7.2 Resource definition 293

-

6.7.3 Resource methods 294

-

6.7.3.1 PATCH 294

-

6.7.3.2 DELETE 295

-

6.7.3.3 PUT 296

-

6.8 Resource: csourceRegistrations/ 298

-

6.8.1 Description 298

-

6.8.2 Resource definition 298

-

6.8.3 Resource methods 298

-

6.8.3.1 POST 298

-

6.8.3.2 GET 299

-

6.9 Resource: csourceRegistrations/{registrationId} 301

-

6.9.1 Description 301

-

6.9.2 Resource definition 301

-

6.9.3 Resource methods 301

-

6.9.3.1 GET 301

-

6.9.3.2 PATCH 302

-

6.9.3.3 DELETE 303

-

6.10 Resource: subscriptions/ 304

-

6.10.1 Description 304

-

6.10.2 Resource definition 304

-

6.10.3 Resource methods 304

-

6.10.3.1 POST 304

-

6.10.3.2 GET 305

-

6.11 Resource: subscriptions/{subscriptionId} 305

-

6.11.1 Description 305

-

6.11.2 Resource definition 305

-

6.11.3 Resource methods 306

-

6.11.3.1 GET 306

-

6.11.3.2 PATCH 306

-

6.11.3.3 DELETE 307

-

6.12 Resource: csourceSubscriptions/ 308

-

6.12.1 Description 308

-

6.12.2 Resource definition 308

-

6.12.3 Resource methods 308

-

6.12.3.1 POST 308

-

6.12.3.2 GET 309

-

6.13 Resource: csourceSubscriptions/{subscriptionId} 310

-

6.13.1 Description 310

-

6.13.2 Resource definition 310

-

6.13.3 Resource methods 310

-

6.13.3.1 GET 310

-

6.13.3.2 PATCH 311

-

6.13.3.3 DELETE 312

-

6.14 Resource: entityOperations/create 312

-

6.14.1 Description 312

-

6.14.2 Resource definition 313

-

6.14.3 Resource methods 313

-

6.14.3.1 POST 313

-

6.15 Resource: entityOperations/upsert 314

-

6.15.1 Description 314

-

6.15.2 Resource definition 314

-

6.15.3 Resource methods 315

-

6.15.3.1 POST 315

-

6.16 Resource: entityOperations/update 316

-

6.16.1 Description 316

-

6.16.2 Resource definition 317

-

6.16.3 Resource methods 317

-

6.16.3.1 POST 317

-

6.17 Resource: entityOperations/delete 318

-

6.17.1 Description 318

-

6.17.2 Resource definition 318

-

6.17.3 Resource methods 319

-

6.17.3.1 POST 319

-

6.18 Resource: temporal/entities/ 320

-

6.18.1 Description 320

-

6.18.2 Resource definition 320

-

6.18.3 Resource methods 320

-

6.18.3.1 POST 320

-

6.18.3.2 GET 321

-

6.19 Resource: temporal/entities/{entityId} 324

-

6.19.1 Description 324

-

6.19.2 Resource definition 324

-

6.19.3 Resource methods 325

-

6.19.3.1 GET 325

-

6.19.3.2 DELETE 327

-

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

-

6.20.1 Description 328

-

6.20.2 Resource definition 328

-

6.20.3 Resource methods 328

-

6.20.3.1 POST 328

-

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

-

6.21.1 Description 329

-

6.21.2 Resource definition 329

-

6.21.3 Resource methods 329

-

6.21.3.1 DELETE 329

-

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

-

6.22.1 Description 330

-

6.22.2 Resource definition 330

-

6.22.3 Resource methods 330

-

6.22.3.1 PATCH 330

-

6.22.3.2 DELETE 331

-

6.23 Resource: entityOperations/query 332

-

6.23.1 Description 332

-

6.23.2 Resource definition 332

-

6.23.3 Resource methods 332

-

6.23.3.1 POST 332

-

6.24 Resource: temporal/entityOperations/query 334

-

6.24.1 Description 334

-

6.24.2 Resource definition 334

-

6.24.3 Resource methods 334

-

6.24.3.1 POST 334

-

6.25 Resource: types/ 335

-

6.25.1 Description 335

-

6.25.2 Resource definition 336

-

6.25.3 Resource methods 336

-

6.25.3.1 GET 336

-

6.26 Resource: types/{type} 337

-

6.26.1 Description 337

-

6.26.2 Resource definition 337

-

6.26.3 Resource methods 337

-

6.26.3.1 GET 337

-

6.27 Resource: attributes/ 338

-

6.27.1 Description 338

-

6.27.2 Resource definition 338

-

6.27.3 Resource methods 338

-

6.27.3.1 GET 338

-

6.28 Resource: attributes/{attrId} 339

-

6.28.1 Description 339

-

6.28.2 Resource definition 339

-

6.28.3 Resource methods 339

-

6.28.3.1 GET 339

-

6.29 Resource: jsonldContexts/ 340

-

6.29.1 Description 340

-

6.29.2 Resource definition 340

-

6.29.3 Resource methods 340

-

6.29.3.1 POST 340

-

6.29.3.2 GET 341

-

6.30 Resource: jsonldContexts/{contextId} 342

-

6.30.1 Description 342

-

6.30.2 Resource definition 342

-

6.30.3 Resource methods 342

-

6.30.3.1 GET 342

-

6.30.3.2 DELETE 343

-

6.31 Resource: entityOperations/merge 344

-

6.31.1 Description 344

-

6.31.2 Resource definition 344

-

6.31.3 Resource methods 344

-

6.31.3.1 POST 344

-

6.32 Resource: entityMaps/{entityMapId} 346

-

6.32.1 Description 346

-

6.32.2 Resource definition 346

-

6.32.3 Resource methods 346

-

6.32.3.1 GET 346

-

6.32.3.2 PATCH 347

-

6.32.3.3 DELETE 347

-

6.33 Resource: info/sourceIdentity 348

-

6.33.1 Description 348

-

6.33.2 Resource definition 348

-

6.33.3 Resource methods 348

-

6.33.3.1 GET 348

-

6.34 Resource: entityMaps 349

-

6.34.1 Description 349

-

6.34.2 Resource definition 349

-

6.34.3 Resource methods 349

-

6.34.3.1 GET 349

-

6.34.3.2 POST 350

-

6.35 Resource: temporal/entityMaps 351

-

6.35.1 Description 351

-

6.35.2 Resource definition 351

-

6.35.3 Resource methods 351

-

6.35.3.1 GET 351

-

6.35.3.2 POST 352

-

6.36 Resource: snapshots 353

-

6.36.1 Description 353

-

6.36.2 Resource definition 353

-

6.36.3 Resource methods 353

-

6.36.3.1 POST 353

-

6.36.3.2 DELETE 354

-

6.37 Resource: snapshots/{snapshotId} 355

-

6.37.1 Description 355

-

6.37.2 Resource definition 355

-

6.37.3 Resource methods 355

-

6.37.3.1 GET 355

-

6.37.3.2 PATCH 356

-

6.37.3.3 DELETE 356

-

6.38 Resource: snapshots/{snapshotId}/clone 357

-

6.38.1 Description 357

-

6.38.2 Resource definition 357

-

6.38.3 Resource methods 357

-

6.38.3.1 POST 357

-

7 API MQTT Notification Binding 358

-

7.1 Introduction 358

-

7.2 Notification behaviour 358

-

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

-

A.1 Introduction 360

-

A.2 Entity identifiers 360

-

A.3 NGSI-LD namespace 360

-

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

-

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

-

C.1 Introduction 367

-

C.2 Entity Representation 367

-

C.2.1 Property Graph 367

-

C.2.2 Vehicle Entity 368

-

C.2.3 Parking Entity 381

-

C.2.4 @context 387

-

C.3 Context Source Registration 387

-

C.4 Context Subscription 388

-

C.5 HTTP REST API Examples 389

-

C.5.1 Introduction 389

-

C.5.2 Create Entity of Type Vehicle 389

-

C.5.2.1 HTTP Request 389

-

C.5.2.2 HTTP Response 389

-

C.5.3 Query Entities 389

-

C.5.3.1 Introduction 389

-

C.5.3.2 HTTP Request 389

-

C.5.3.3 HTTP Response 390

-

C.5.4 Query Entities (Pagination) 390

-

C.5.4.1 Introduction 390

-

C.5.4.2 HTTP Request 390

-

C.5.4.3 HTTP Response 390

-

C.5.5 Temporal Query 391

-

C.5.5.1 Introduction 391

-

C.5.5.2 HTTP Request #1 391

-

C.5.5.3 HTTP Response #1 391

-

C.5.5.3 HTTP Request #2 391

-

C.5.5.4 HTTP Response #2 392

-

C.5.6 Temporal Query (Simplified Representation) 392

-

C.5.6.1 Introduction 392

-

C.5.6.2 HTTP Request 392

-

C.5.6.3 HTTP Response 392

-

C.5.7 Retrieve Available Entity Types 393

-

C.5.7.1 Introduction 393

-

C.5.7.2 HTTP Request 393

-

C.5.7.3 HTTP Response 393

-

C.5.8 Retrieve Details of Available Entity Types 394

-

C.5.8.1 Introduction 394

-

C.5.8.2 HTTP Request 394

-

C.5.8.3 HTTP Response 394

-

C.5.9 Retrieve Available Entity Type Information 395

-

C.5.9.1 Introduction 395

-

C.5.9.2 HTTP Request 395

-

C.5.9.3 HTTP Response 395

-

C.5.10 Retrieve Available Attributes 396

-

C.5.10.1 Introduction 396

-

C.5.10.2 HTTP Request 396

-

C.5.10.3 HTTP Response 396

-

C.5.11 Retrieve Details of Available Attributes 396

-

C.5.11.1 Introduction 396

-

C.5.11.2 HTTP Request 396

-

C.5.11.3 HTTP Response 397

-

C.5.12 Retrieve Available Attribute Information 397

-

C.5.12.1 Introduction 397

-

C.5.12.2 HTTP Request 397

-

C.5.12.3 HTTP Response 398

-

C.5.13 Query Entities (Natural Language Filtering) 398

-

C.5.13.1 Introduction 398

-

C.5.13.2 HTTP Request 398

-

C.5.13.3 HTTP Response 398

-

C.5.14 Temporal Query (Aggregated Representation) 399

-

C.5.14.1 Introduction 399

-

C.5.14.2 HTTP Request 399

-

C.5.14.3 HTTP Response 399

-

C.5.15 Scope Queries 400

-

C.5.15.1 Introduction 400

-

C.5.15.2 HTTP Request 400

-

C.5.15.3 HTTP Response 400

-

C.5.16 Temporal Scope Queries 401

-

C.5.16.1 Introduction 401

-

C.5.16.2 HTTP Request 401

-

C.5.16.3 HTTP Response 401

-

C.6 Date Representation 403

-

C.7 @context utilization clarifications 404

-

C.8 Link header utilization clarifications 405

-

C.9 @context processing clarifications 407

-

C.10 ValueType datatype utilization clarifications 408

-

C.11 Entity with digital signature for a Property 409

-

Annex D (informative): Transformation Algorithms 410

-

D.1 Introduction 410

-

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

-

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

-

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

-

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

-

Annex F (informative): Conventions and syntax guidelines 414

-

Annex G (informative): Localization and Internationalization Support 415

-

G.0 Foreword 415

-

G.1 Introduction 415

-

G.1.0 Foreword 415

-

G.1.1 Associating an Entity with a Natural Language 415

-

G.1.2 Associating a Property with a Natural Language 415

-

G.1.3 Associating as equivalent entity 416

-

G.2 Natural Language Collation Support 416

-

G.2.0 Foreword 416

-

G.2.1 Maintain collations as metadata 417

-

G.2.2 Route language sensitive queries via a proxy 417

-

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

-

G.3.0 Foreword 417

-

G.3.1 Localizing Dates 417

-

Annex H (informative): Suggested actuation workflows 419

-

H.1 Actuators and feedback to the consumer 419

-

H.2 Architecture for actuation 419

-

H.3 Structure of Commands and additional Properties 420

-

H.3.0 Introduction 420

-

H.3.1 Property for listing available commands 421

-

H.3.2 Properties for command endpoints 421

-

H.4 Communication model 423

-

H.4.1 Possible communication models 423

-

H.4.2 Subscription/notification model 423

-

H.4.3 Forwarding model 424

-

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

-

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

-

Annex I (informative): Change history 429

-

History 432

-
- - - - - diff --git a/API/1-intellectual-property-rights.html b/API/1-intellectual-property-rights.html deleted file mode 100644 index c4eea59e7dcab823c547fc31d780693b7cf0fe9f..0000000000000000000000000000000000000000 --- a/API/1-intellectual-property-rights.html +++ /dev/null @@ -1,1525 +0,0 @@ - - - - - - - -Intellectual Property Rights - - - - - - - - - - - - -
-

Intellectual Property Rights

-
-

Essential patents

-
-

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.

-
-

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

-
- - - - - diff --git a/API/10-tabapi-operation-definition.html b/API/10-tabapi-operation-definition.html deleted file mode 100644 index 32f19a2f50dc94f32cb3c92b46e9d1a7a0b7e5d1..0000000000000000000000000000000000000000 --- a/API/10-tabapi-operation-definition.html +++ /dev/null @@ -1,15072 +0,0 @@ - - - - - - - -5 API Operation Definition - - - - - - - - - - - - -
-

5 API Operation Definition

-

5.1 Introduction

-

This clause defines data structures and operations of the NGSI-LD API. No specific binding is assumed. Clause 6 maps these operations and data types to the HTTP REST binding.

-
-
-

NOTE:

-
-
-

In UML diagrams dotted arrows denote a response to a request.

-
-
-

5.2 Data Types

-

5.2.1 Introduction

-

Implementations shall support the data types defined by the clauses below. For each member defined by each data type (including nested ones) a term shall be added to the Core @context, as mandated by clause 4.5.

-

None of the members described admit a null value directly, as when a JSON-LD processor encounters null, the associated entry or value is always removed when expanding the JSON-LD document.

-

However, in the context of a partial update or merge operation (see clauses 5.5.8 and 5.5.12), an NGSI-LD Null shall be used to indicate the removal of a target member, as explained in clause 4.5.0. In all other cases, implementations shall raise an error of type BadRequestData if an NGSI-LD Null value is encountered.

-

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

-

Non-normative JSON Schema [i.11] definitions of the referred data types are also available at [i.13].

-

The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [23], which extends the use of characters to Unicode characters [22] beyond the ASCII character set, enabling the support of languages other than English.

-

5.2.2 Common members

-

The JSON-LD representation of NGSI-LD Entity, Property, Relationship, Context Source Registration and Subscription can include the common members described by Table 5.2.2‑1.

-

Those members are read-only, and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-

In query or retrieve operations implementations shall only generate common members (Table 5.2.2‑1) when the Context Consumerexplicitly asks for their inclusion. Clause 6.3.11 defines the mechanism offered by the HTTP binding for such purpose.

-
-

Table 5.2.2-1: Common members of NGSI-LD elements

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-createdAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity creation timestamp. See clause 4.8 -
-deletedAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity deletion timestamp. See clause 4.8 It is only used in notifications reporting deletions and in the temporal representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) and LanguageProperties (clause 5.2.32) and VocabProperties (clause 5.2.35) and JsonProperties (clause 5.2.38) -
-modifiedAt -
-string -
-DateTime (clause 4.6.3) -
-0..1 -
-Entity last modification timestamp. See clause 4.8 -
-

5.2.3 @context

-

When encoding NGSI-LD Entities, Context Source Registrations, Subscriptions and Notifications, as pure JSON-LD (MIME type “application/ld+json”),

-

an array (flattened to a single string if necessary), containing a user

-

@context

-

where present, and the core

-

@context (as described in clause 4.4) shall be included as a special member of the corresponding JSON-LD Object. Table 5.2.3‑1 gives a precise definition of this special member.

-
-

Table 5.2.3-1: JSON-LD @context tagged member

-
- ------- - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. -
-

5.2.4 Entity

-

This type represents the data needed to define an NGSI-LD Entity as mandated by clause 4.5.1.

-

The supported JSON members shall follow the requirements provided in Table 5.2.4‑1.

-
-

Table 5.2.4-1: NGSI-LD Entity data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Entity ID. -
-type -
-String or String[] -
-1 -
-Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed -
-
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Entity. See clause 4.22 -
-location -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-Default geospatial Property of an entity. See clause 4.7 -
-observationSpace -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-See clause 4.7 -
-operationSpace -
-GeoProperty -
-See datatype definition in clause 5.2.7 -
-0..1 -
-See clause 4.7 -
-scope -
-String or String[] -
-See clause 4.18 -
-0..1 -
-Scope -
-<Property name> -
-Property or Property[] (see note 1) -
-See datatype definitions in clauses 5.2.5 -
-0..N -
-Property as mandated by clause 4.5.2 -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperty as mandated by clause 4.5.2 -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperty as mandated by clause 4.5.18 -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperty as mandated by clause 4.5.24 -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperty as mandated by clause 4.5.20 -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperty as mandated by clause 4.5.21 -
-<Relationship name> -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationship as mandated by clause 4.5.3 -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationship as mandated by clause 4.5.22 -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

5.2.5 Property

-

This type represents the data needed to define a Property as mandated by clause 4.5.2.

-

The supported JSON members shall follow the requirements provided in Table 5.2.5‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute type member can be omitted as type=“Property” can be inferred from the presence of the value member. Furthermore, in the concise representation of a Property, the value member cannot be a GeoJSON Object (as defined in clause 4.7) as it would be interpreted as a GeoProperty (see clause 5.2.7).

-
-

Table 5.2.5-1: NGSI-LD Property data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Property” -
-1 -
-Node type. -
-value -
-Any JSON value as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-1 -
-Property Value. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Property. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the Property guaranteeing its integrity. See annex C.11 for an example. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8 -
-unitCode -
-String -
-As mandated by [15] -
-0..1 -
-Property Value’s unit code -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the Property Value. A String Value which shall be type coerced to a URI based on the supplied @context -
-
-<Property name> -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the Property -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the Property -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the Property -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the Property -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the Property -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the Property -
-<Relationship name> -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the Property -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the Property -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.5-2) of the Property data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.5-2: Output only members of the NGSI-LD Property data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8 -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8 -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of Properties -
-0..1 -
-URI uniquely identifying a Property instance as mandated by clause 4.5.7 -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8 -
-previousValue -
-Any JSON value as defined by IETF RFC 8259 [6] -
-Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous Property Value -
-

5.2.6 Relationship

-

This type represents the data needed to define a Relationship as mandated by clause 4.5.3.

-

The supported JSON members shall follow the requirements provided in Table 5.2.6‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute typemember can be omitted as type=“Relationship” can be inferred from the presence of the object member.

-
-

Table 5.2.6-1: NGSI-LD Relationship data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Relationship” -
-1 -
-Node type -
-object -
-String or String[] -
-Valid URI or an Array of Valid URIs -
-1 -
-Relationship’s target object -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of target relationship objects -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the Relationship. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the Relationship guaranteeing its integrity. -
-objectType -
-String or String[] -
-0..1 -
-Node Type of the Relationship’s target object. Both short hand string(s) (type name) or URI(s) are allowed -
-
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8 -
-<Property name> -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the Relationship -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the Relationship -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the Relationship -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the Relationship -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the Relationship -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the Relationship -
-<Relationship name> -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the Relationship -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the Relationship -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.6-2) of the Relationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.6-2: Output only members of the NGSI-LD Relationship data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8 -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8 -
-entity -
-Entity or Entity[] (see note) -
-

See datatype definition in clause 5.2.4.

-

Only used in Linked Entity Retrieval, if the join=inline option is explicitly requested

-
-0..1 -
-An inline Entity obtained by Linked Entity Retrieval, corresponding to the Relationship’s target object. See clause 4.5.23.2 -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of Relationships -
-0..1 -
-URI uniquely identifying a Relationship instance as mandated by clause 4.5.8 -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8 -
-previousObject -
-String -
-Valid URI. Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous Relationship’s target object -
-
-
-

NOTE:

-
-
-

one-to-N Relationships expand to an array of Entity elements, since there can be more than one target object URI specified.

-
-
-
-

5.2.7 GeoProperty

-

This type represents the data needed to define a GeoProperty.

-

The supported JSON members shall follow the requirements provided in Table 5.2.7‑1 below. The datatype definition defines all the required attributes for the normalized representation. In the concise representation, the Attribute type member can be omitted as “GeoProperty” can be inferred from the presence of the value member holding a GeoJSON Geometry as mandated by clause 4.7.

-
-

Table 5.2.7-1: NGSI-LD GeoProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “GeoProperty” -
-1 -
-Node type -
-value -
-JSON Object -
-As mandated by clause 4.7 -
-1 -
-Geolocation encoded as GeoJSON [8] -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the GeoProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the GeoProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8 -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the GeoProperty Value. A String Value which shall be type coerced to a URI based on the supplied @context -
-
-<Property name> -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the GeoProperty -
-GeoProperty or GeoProperty[] (see note 1) -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoPropertiesof the GeoProperty -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguagePropertiesof the GeoProperty -
-JsonProperty or JsonProperty[](see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonPropertiesof the GeoProperty -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabPropertiesof the GeoProperty -
-ListProperty or ListProperty[] (see note 1) -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListPropertiesof the GeoProperty -
-<Relationship name> -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the GeoProperty -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationshipsof the GeoProperty -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.7-2) of the GeoProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.7-2: Output only members of the NGSI-LD GeoProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of GeoProperties -
-0..1 -
-URI uniquely identifying a GeoProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousValue -
-Any JSON value as defined by IETF RFC 8259 [6] -
-Only used in Notifications, if the showChanges option is explicitly requested -
-0..1 -
-Previous GeoProperty Value. -
-

5.2.8 EntityInfo

-

This type represents what Entities, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]) can be provided (by Context Sources).

-

The JSON members shall follow the indications provided in Table 5.2.8‑1. id takes precedence over idPattern.

-

Notice that Cardinality of type being 1 implies that it is not possible to register what Entities can be provided by a Context Source just by their id or idPattern (i.e. without specifying their type).

-
-

Table 5.2.8-1: EntityInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String or String[] -
-Fully Qualified Name of an Entity Type or the Entity Type name as a short-hand string. See clause 4.6.2 -
-1 -
-Entity Type (or JSON array, in case of Entities with multiple Entity Types). -
-id -
-String -
-Valid URI -
-0..1 -
-Entity identifier. -
-idPattern -
-String -
-Regular expression as per IEEE 1003.2™ [11] -
-0..1 -
-A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. -
-

5.2.9 CSourceRegistration

-

This type represents the data needed to register a new Context Source.

-

The supported JSON members shall follow the indications provided in Table 5.2.9‑1.

-
-

Table 5.2.9-1: CSourceRegistration data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-

Valid URI.

-

Unique registration identifier. (JSON-LD @id).

-
-0..1 -
-

Generated at creation time, if it is not provided, it will be assigned during registration process and returned to client.

-

It cannot be later modified in update operations.

-
-type -
-String -
-It shall be equal to “ContextSourceRegistration” -
-1 -
-

JSON-LD @type

-

Use reserved type for identifying Context Source Registration.

-
-endpoint -
-String -
-It shall be a dereferenceable URI -
-1 -
-Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD interface. -
-contextSourceInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to provide when contacting the registered Context Source. -
-
-information -
-RegistrationInfo[] -
-See data type definition in clause 5.2.10. Empty array (0 length) is not allowed -
-1 -
-Describes the Entities, Properties and Relationships for which the Context Source may be able to provide information. -
-contextSourceAlias -
-String -
-Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] -
-0..1 -
-

A previously retrieved unique id for a registered Context Source which is used to identify loops.

-

In the multi-tenancy use case (see clause 4.14), this id shall be used to identify a specific Tenant within a registered Context Source.

-
-description -
-String -
-Non-empty string -
-0..1 -
-A description of this Context Source Registration. -
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of Attributes that the Context Source can provide, defined as per clause 4.5.5. -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Provides an expiration date. When passed the Context Source Registration will become invalid and the Context Source might no longer be available. -
-location -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Location for which the Context Sourcemay be able to provide information. -
-
-management -
-

Registration

-

Management

-

Info

-
-See data type definition in clause 5.2.34 -
-0..1 -
-Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. -
-managementInterval -
-TimeInterval -
-See data type definition in clause 5.2.11 -
-0..1 -
-If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The managementInterval specifies the time interval for which the Context Source can provide Entity information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched against the managementInterval for overlap. -
-mode -
-String -
-

It shall be one of:

-

“inclusive”,“exclusive”,“redirect” or “auxiliary”

-

The mode is assumed to be “inclusive” if not explicitly defined

-
-0..1 -
-The definition of the mode of distributed operation (see clause 4.3.6) supported by the registered Context Source. -
-observationInterval -
-TimeInterval -
-See data type definition in clause 5.2.11 -
-0..1 -
-If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity information is also provided, a separate Context Registration is needed for this purpose). The observationInterval specifies the time interval for which the Context Source can provide Entity information as specified by the observedAt Temporal Property. A temporal query based on the observedAt Temporal Property, which is the default, is matched against the observationInterval for overlap. -
-observationSpace -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Geographic location that includes the observation spaces of all entities as specified by their respective observationSpace GeoProperty for which the Context Source may be able to provide information. -
-
-operations -
-String[] -
-Entries are limited to the named API operations and named operation groups (see clause 4.20) -
-0..1 -
-

The definition limited subset of API operations supported by the registered Context Source.

-

If undefined, the default set of operations is “federationOps” (see clause 4.20).

-
-operationSpace -
-GeoJSON Geometry as mandated by clause 4.7 -
-0..1 -
-Geographic location that includes the operation spaces of all entities as specified by their respective operationSpace GeoProperty for which the Context Source may be able to provide information. -
-
-refreshRate -
-String -
-String representing a duration in ISO 8601 format [17] -
-0..1 -
-

An indication of the likely period of time to elapse between updates at this registered endpoint.

-

Brokers may optionally use this information to help implement caching.

-
-registrationName -
-String -
-Non-empty string -
-0..1 -
-A name given to this Context Source Registration -
-scope -
-

String or

-

String[]

-
-Scope(s) -
-0..1 -
-Scopes (see clause 4.18) for which the Context Source has Entities. -
-tenant -
-String -
-0..1 -
-Identifies the Tenant that has to be specified in all requests to the Context Source that are related to the information registered in this Context Source Registration. If not present, the default Tenant is assumed. Should only be present in systems supporting multi-tenancy. -
-
-

The members (defined by Table 5.2.9-2) of the CSourceRegistration data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.9-2: Additional members of the CSourceRegistration data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-lastFailure -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last distributed operation resulting in a failure (for instance, in the HTTP binding, an HTTP response code other than 2xx) was returned. -
-status -
-String -
-

Allowed values:

-

“ok”

-

“failed”

-
-0..1 -
-Read-only., Status of the Registration. It shall be “ok” if the last attempt to perform a distributed operation succeeded. It shall be “failed” if the last attempt to perform a distributed operation failed. -
-timesFailed -
-Number -
-0 or greater value -
-0..1 -
-Number of times that the registration triggered a distributed operation request that failed. -
-timesSent -
-Number -
-0 or greater value -
-0..1 -
-Number of times that the registration triggered a distributed operation, including failed attempts. -
-lastSuccess -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last successfully distributed operation was sent. Created on first successful operation. -
-

5.2.10 RegistrationInfo

-

The supported JSON members shall follow the requirements provided in Table 5.2.10‑1.

-
-

Table 5.2.10-1: RegistrationInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entities -
-EntityInfo[] -
-See data type definition in clause 5.2.8. Empty array (0 length) is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the entities for which the CSource may be able to provide information. -
-propertyNames -
-String[] -
-Property names as short hand strings or URIs. Empty array is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the Properties that the CSource may be able to provide. -
-relationshipNames -
-String[] -
-Relationship names as short hand strings or URIs. Empty array is not allowed. Restrictions in clause 4.3.6 apply as well -
-0..1 -
-Describes the Relationships that the CSource may be able to provide. -
-

At least one element of RegistrationInfo shall be present.

-

5.2.11 TimeInterval

-

The supported JSON members shall follow the requirements provided in Table 5.2.11‑1.

-
-

Table 5.2.11-1: TimeInterval data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-startAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Describes the start of the time interval -
-endAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Describes the end of the time interval. If not present the interval is open -
-

5.2.12 Subscription

-

This datatype represents a Context Subscription.

-

The supported JSON members shall follow the requirements provided in Table 5.2.12‑1.

-
-

Table 5.2.12-1: Subscription data type definition

-
- -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-0..1 -
-

Subscription identifier (JSON-LD @id). Generated at creation time, if it is not provided, it will be assigned during subscription process and returned to client.

-

It cannot be later modified in update operations.

-
-type -
-String -
-It shall be equal to “Subscription” -
-1 -
-JSON-LD @type. -
-entities -
-EntitySelector[] -
-

See data type definition in clause 5.2.33. Empty array (0 length) is not allowed.

-

Mandatory if timeInterval is present, unless the execution of the request is limited to local scope (see clause 5.5.13)

-
-0..1 -
-Entities subscribed. -
-notification -
-NotificationParams -
-See data type definition in clause 5.2.14 -
-1 -
-Notification details. -
-notificationTrigger -
-String[] -
-Valid notification triggers are “entityCreated”,“entityUpdated”,“entityDeleted”,“attributeCreated”,“attributeUpdated”,“attributeDeleted” -
-0..1 -
-The notification triggers listed indicate what kind of changes shall trigger a notification. If not present, the default is the combination “attributeCreated” and “attributeUpdated”. “entityUpdated” is equivalent to the combination “attributeCreated”, “attributeUpdated” and “attributeDeleted” -
-watchedAttributes -
-String[] -
-

Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed.

-

if timeInterval is present it shall not appear (0 cardinality)

-
-0..1 -
-Watched Attributes (Properties or Relationships). If not defined it means any Attribute. -
-q -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Query that shall be met by subscribed entities in order to trigger the notification. -
-geoQ -
-GeoQuery -
-See data type definition in clause 5.2.13 -
-0..1 -
-Geoquery that shall be met by subscribed entities in order to trigger the notification. -
-scopeQ -
-String -
-See clause 4.19 -
-0..1 -
-Scope query. -
-temporalQ -
-TemporalQuery -
-See data type definition in clause 5.2.21 -
-0..1 -
-Temporal Query to be used only in Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal information. -
-csf -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Context source filter that shall be met by Context Source Registrations describing Context Sources to be used for Entity Subscriptions. -
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-description -
-String -
-0..1 -
-Subscription description. -
-
-expandValues -
-String -
-Comma separated list of attribute names -
-0..1 -
-Values of the identified attributes should be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-Expiration date for the subscription. -
-isActive -
-Boolean -
-true by default -
-0..1 -
-Allows clients to temporarily pause the subscription by making it inactive. true indicates that the Subscription is under operation. false indicates that the subscription is paused, and notifications shall not be delivered. -
-jsonKeys -
-String -
-Comma separate list of attribute names -
-0..1 -
-Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-jsonldContext -
-String -
-Dereferenceable URI -
-0..1 -
-The dereferenceable URI of the JSON-LD @context to be used when sending a notification resulting from the subscription. If not provided, the @context used for the subscription shall be used as a default. -
-lang -
-String -
-A natural language filter in the form of a IETF RFC 5646 [28] language code -
-0..1 -
-Language filter to be applied to the query (clause 4.15). -
-localOnly -
-Boolean -
-0..1 -
-If localOnly=true then the subscription only pertains to the Entities stored locally. In case the Subscription pertains to a Snapshot it is always local, regardless of whether localOnly is set to true or not. -
-
-ngsildConformance -
-String -
-A semantically versioned string in the form major.minor, which conforms to a version of the NGSI-LD specification -
-0..1 -
-If provided the notification shall undergo a backwards compatibility operation as defined by clause 4.3.6.8 and be amended to conform to the supplied version of the NGSI-LD specification. -
-splitEntities -
-Boolean -
-default decided by implementation; it should be configurable. The parameter does not apply in case localOnly is true. -
-0..1 -
-If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. -
-subscriptionName -
-String -
-0..1 -
-A (short) name given to this Subscription. -
-
-throttling -
-Number -
-Greater than 0. Fractional values are allowed. If timeInterval is present it shall not appear (0 cardinality) -
-0..1 -
-Minimal period of time in seconds which shall elapse between two consecutive notifications. -
-timeInterval -
-Number -
-

Greater than 0

-

if watchedAttributes is present it shall not appear (0 cardinality)

-
-0..1 -
-Indicates that a notification shall be delivered periodically regardless of attribute changes. Actually, when the time interval (in seconds) specified in this value field is reached. -
-

At least one of (a) entities or (b) watchedAttributes shall be present, unless the member localOnlyis set to true, in which case the execution of the request is limited to local scope (see clause 5.5.13).

-

The members (defined by Table 5.2.12-2) of the Subscription data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.12-2: Additional members of the Subscription data type

-
- ------- - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-status -
-String -
-

Allowed values:

-

“active”

-

“paused”

-

“expired”

-
-0..1 -
-Read-only. Provided by the system when querying the details of a subscription -
-

5.2.13 GeoQuery

-

This datatype represents a geoquery used for Subscriptions.

-

The supported JSON members shall follow the requirements provided in Table 5.2.13‑1.

-
-

Table 5.2.13-1: GeoQuery data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-coordinates -
-JSON Array or String -
-A JSON Array coherent with the geometry type as per IETF RFC 7946 [8] -
-1 -
-Coordinates of the reference geometry. For the sake of JSON-LD compatibility It can be encoded as a string as described in clause 4.7.1. -
-geometry -
-String -
-A valid GeoJSON [8] geometry type excepting GeometryCollection -
-1 -
-Type of the reference geometry. -
-georel -
-String -
-A valid geo-relationship as defined by clause 4.10 -
-1 -
-Geo-relationship (“near”, “within”, etc.). -
-geoproperty -
-String -
-Attribute name as short hand string or URI -
-0..1 -
-Specifies the GeoProperty to which the GeoQuery is to be applied. If not present, the default GeoProperty is location. -
-

5.2.14 NotificationParams

-

5.2.14.1 NotificationParams data type definition

-

This datatype represents the parameters that allow to convey the details of a notification.

-

The supported JSON members shall follow the requirements provided in Table 5.2.14.1‑1.

-
-

Table 5.2.14.1-1: NotificationParams data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-endpoint -
-Endpoint -
-See data type definition in clause 5.2.15 -
-1 -
-Notification endpoint details. -
-attributes -
-String[] -
-Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed -
-0..1 -
-

A synonym for pick, except that id, type, scope are not allowed. Deprecated

-

Attribute names to be included in the notification payload body. If undefined it will mean all Attributes.

-
-format -
-String -
-It shall be one of: “normalized”, “concise”, “simplified” (or its synonym “keyValues”) -
-0..1 -
-Conveys the representation format of the entities delivered at notification time. By default, it will be in the normalized format. -
-join -
-String -
-It shall be one of: “flat”, “inline”, “@none” -
-0..1 -
-

String representing the type of Linked Entity retrieval to apply.

-

By default, it will be “@none”.

-
-joinLevel -
-Number -
-Positive Integer -
-0..1 -
-Depth of Linked Entity retrieval to apply. Default is 1. Only applicable if join parameter is “flat”, or “inline”. -
-omit -
-String[] -
-Entity member (“id”, “type”, “scope”or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, the specified Entity members are removed from each Entity within the payload. -
-pick -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name as a valid attribute projection language string as per clause 4.21). Empty array (0 length) is not allowed -
-0..1 -
-When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. -
-showChanges -
-Boolean -
-false by default -
-0..1 -
-

If true the previous value (previousValue) of Properties or languageMap (previousLanguageMap) of Language Properties or object (previousObject) of Relationships is provided in addition to the current one. This requires that it exists, i.e. in case of modifications and deletions, but not in the case of creations.

-

showChanges cannot be true in case format is “keyValues”.

-
-sysAttrs -
-Boolean -
-false by default -
-0..1 -
-If true, the system generated attributes createdAt and modifiedAt and the system attribute expiresAt are included in the response payload body, in the case of a deletion also deletedAt. -
-

5.2.14.2 Output only members

-

The following output only members (defined by Table 5.2.14.2-1) of the NotificationParams data structure are also defined. They are read-only and shall be automatically generated by NGSI-LD implementations. They shall not be provided by Context Subscribers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-

In query or retrieve operations involving Subscriptions, implementations shall generate them as part of their representation.

-
-

Table 5.2.14.2-1: Output only members of the NotificationParams data structure

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-lastFailure -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last notification resulting in failure (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. Provided by the system when querying the details of a subscription -
-lastNotification -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last notification has been sent. Provided by the system when querying the details of a subscription -
-lastSuccess -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp corresponding to the instant when the last successful (200 OK response) notification has been sent. Provided by the system when querying the details of a subscription -
-status -
-String -
-

Allowed values:

-

“ok”, “failed”

-
-0..1 -
-Status of the Notification. It shall be “ok” if the last attempt to notify the subscriber succeeded. It shall be “failed” if the last attempt to notify the subscriber failed -
-timesFailed -
-Number -
-Greater than 0 -
-0..1 -
-Number of times an unsuccessful response (or timeout) has been received when delivering the notification. Provided by the system when querying the details of a subscription -
-timesSent -
-Number -
-Greater than 0 -
-0..1 -
-Number of times that the notification has been sent. Provided by the system when querying the details of a subscription -
-

5.2.15 Endpoint

-

This datatype represents the parameters that are required in order to define an endpoint for notifications. This can include, in addition the endpoint’s URI, a generic{key, value} array, named receiverInfo, which contains, in a generalized form, whatever extra information the Context Broker shall convey to the receiver in order for the Context Broker to successfully communicate with receiver (e.g. Authorization material), or for the receiver to correctly interpret the received content (e.g. the Link URL to fetch an @context). Additionally, it can include another generic{key, value} array, named notifierInfo, which contains the configuration that the Context Broker needs to know in order to correctly set up the communication channel towards the receiver (e.g. MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in clause 7.2).

-

The supported JSON members shall follow the indications provided in Table 5.2.15‑1.

-
-

Table 5.2.15-1: Endpoint data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-uri -
-String -
-Dereferenceable URI -
-1 -
-URI which conveys the endpoint which will receive the notification. -
-accept -
-String -
-

MIME type. It shall be one of:

-

“application/json”

-

“application/ld+json”

-

“application/geo+json”

-
-0..1 -
-Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). If not present, default is “application/json”. -
-cooldown -
-Number -
-Greater than 0 -
-0..1 -
-Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent. -
-notifierInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to set up the communication channel. -
-
-receiverInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to the receiver. -
-
-timeout -
-Number -
-Greater than 0 -
-0..1 -
-Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. The NGSI-LD system can override this value. This only applies if the binding protocol always returns a response. -
-

5.2.16 BatchOperationResult

-

This datatype represents the result of a batch operation.

-

The supported JSON members shall follow the indications provided in Table 5.2.16‑1.

-
-

Table 5.2.16-1: BatchOperationResult data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-errors -
-BatchEntityError[] -
-1 -
-One array item per Element in error. Empty Array if no errors happened. -
-
-success -
-String[] -
-Array of valid URIs -
-1 -
-Array of Entity IDs corresponding to the Elements that were successfully treated by the concerned operation. Empty Array if no Element was successfully treated. -
-

5.2.17 BatchEntityError

-

This datatype represents an error raised (associated to a particular Entity) during the execution of a batch or distributed operation.

-

The supported JSON members shall follow the indications provided in Table 5.2.17‑1.

-
-

Table 5.2.17-1: BatchEntityError data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entityId -
-String -
-Valid URI -
-1 -
-Entity ID corresponding to the Entity in error -
-error -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-One instance per Entity in error -
-
-registrationId -
-String -
-Valid URI -
-0..1 -
-Registration Id corresponding to a failed distributed operation (optional) -
-

5.2.18 UpdateResult

-

This datatype represents the result of Attribute update (append or update) operations in the NGSI-LD API regardless of whether local or distributed.

-

The supported JSON members shall follow the indications provided in Table 5.2.18‑1.

-
-

Table 5.2.18-1: UpdateResult data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-notUpdated -
-NotUpdatedDetails[] -
-See clause 5.2.19 -
-1 -
-List which contains the Attributes (represented by their name) that were not updated, together with the reason for not being updated. -
-updated -
-String[] -
-1 -
-List of Attributes (represented by their name) that were appended or updated. -
-
-

5.2.19 NotUpdatedDetails

-

This datatype represents additional information provided by an implementation when an Attribute update did not happen. See also clause 5.2.18.

-

The supported JSON members shall follow the indications provided in Table 5.2.19‑1.

-
-

Table 5.2.19-1: NotUpdatedDetails data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-attributeName -
-String -
-1 -
-Attribute name -
-
-reason -
-String -
-1 -
-Reason for not having changed such Attribute -
-
-registrationId -
-String -
-Valid URI -
-0..1 -
-Registration Id corresponding to a failed distributed operation (optional) -
-

5.2.20 EntityTemporal

-

This datatype represents the Temporal Evolution of an Entity.

-

This is the same datatype as mandated by clause 5.2.4 with the only deviation that the representation of Properties and Relationships shall be the temporal one, as defined in clauses 4.5.7 and 4.5.8. Alternatively it is possible to specify the EntityTemporal by using the “Simplified temporal representation of an Entity”, as defined in clause 4.5.9.

-

5.2.21 TemporalQuery

-

This datatype represents a temporal query.

-

The supported JSON members shall follow the requirements provided in Table 5.2.21‑1.

-
-

Table 5.2.21-1: TemporalQuery data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-timeAt -
-String representing the timeAt parameter as defined by clause 4.11 -
-It shall be a DateTime -
-1 -
-
-timerel -
-String -
-Allowed values: “before”, “after” and “between” -
-1 -
-Represents the temporal relationship as defined by clause 4.11 -
-aggrMethods -
-Comma separated list of string -
-It shall be 1 if aggregatedValues is present in the options parameter -
-0..1 -
-Each String represents an aggregation method, as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-
-endTimeAt -
-String representing the endTimeAt parameter as defined by clause 4.11 -
-It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between” -
-0..1 -
-
-lastN -
-Positive integer -
-0..1 -
-Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. -
-
-timeproperty -
-String representing a Temporal Property name -
-Allowed values: “observedAt”, “createdAt”, “modifiedAt”and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8) -
-0..1 -
-
-

5.2.22 KeyValuePair

-

This datatype represents the optional information that is required when contacting an endpoint for notifications.

-

The supported members shall follow the indications provided in Table 5.2.22‑1. They are intended to represent a key/value pair.

-

Example optional information includes additional HTTP Headers such as:

-
-
    -
  • The HTTP Authentication Header.
    • -
  • The HTTP Prefer Header (IETF RFC 7240 [26]) used when notifying the GeoJSON Endpoint.
    • -
-
-
-

Table 5.2.22-1: KeyValuePair data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-key -
-String -
-Binding-dependent -
-1 -
-The key of the key/value pair -
-value -
-String -
-Binding-dependent -
-1 -
-The value of the key/value pair -
-

5.2.23 Query

-

This datatype represents the information that is required in order to convey a query when a “Query Entities” operation or a “Query Temporal Evolution of Entities” operation is to be performed (as per clauses 5.7.2 and 5.7.4, respectively).

-

The supported JSON members shall follow the requirements provided in Table 5.2.23‑1.

-
-

Table 5.2.23-1: Query data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “Query” -
-1 -
-JSON-LD @type -
-entities -
-EntitySelector[] -
-See data type definition in clause 5.2.33. Empty array (0 length) is not allowed -
-0..1 -
-Entity IDs, id pattern and Entity types that shall be matched by Entities in order to be retrieved. -
-q -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Query that shall be matched by Entities in order to be retrieved. -
-geoQ -
-GeoQuery -
-See data type definition in clause 5.2.13 -
-0..1 -
-Geoquery that shall be matched by Entities in order be retrieved. -
-scopeQ -
-String -
-See clause 4.19 -
-0..1 -
-Scope query. -
-temporalQ -
-TemporalQuery -
-See data type definition in clause 5.2.21 -
-0..1 -
-Temporal Query to be present only for “Query Temporal Evolution of Entities” operation (clause 5.7.4). -
-attrs -
-String[] -
-

Attribute name as short hand strings or URIs.

-

Empty array (0 length) is not allowed

-
-0..1 -
-

A synonym for a combination of the pick andq members. Deprecated

-

List of Attributes that shall be matched by Entities in order to be retrieved. If not present all Attributes will be retrieved.

-
-omit -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, the specified Entity members are removed from each Entity within the payload. -
-pick -
-String[] -
-Entity member (“id”, “type”, “scope” or a projected Attribute name) as a valid attribute projection language string as per clause 4.21. Empty array (0 length) is not allowed -
-0..1 -
-When defined, every Entity within the payload body is reduced down to only contain the specified Entity members. -
-aggrParams -
-AggregationParams -
-See data type definition in clause 5.2.44. -
-0..1 -
-

Aggregation parameters required for supporting aggregation methods in to be present only for “QueryTemporal Evolution of Entities” operation (clause 5.7.4).

-

Only applicable if “aggregatedValues” is present in theformat or options parameter.

-
-csf -
-String -
-A valid query string as per clause 4.9 -
-0..1 -
-Context source filter that shall be matched by Context Source Registrations describing Context Sources to be used for retrieving Entities. -
-containedBy -
-String[] -
-Comma separated list of URIs. Empty array (0 length) is not allowed -
-0..1 -
-

List of entity ids which have previously been encountered whilst retrieving the Entity Graph.

-

Only applicable if joinLevel is present.

-

Only applicable for the “Retrieve Entity” (clause 5.7.1) and “Query Entities” operations (clause 5.7.2).

-
-datasetId -
-String[] -
-Valid URIs,“@none” for including the default Attribute instances. -
-0..1 -
-Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-expandValues -
-String -
-Comma separated list of attribute names -
-0..1 -
-Values of the identified attributes should be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-
-entityMapLifetime -
-String -
-String representing a duration in ISO 8601 format [17] -
-0..1 -
-Suggested duration for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-jsonKeys -
-String -
-Comma separate list of attribute names -
-0..1 -
-Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query. -
-join -
-String -
-It shall be one of: “flat”, “inline”, “@none” -
-0..1 -
-

String representing the type of Linked Entity retrieval to apply.

-

By default, it will be “@none”.

-
-joinLevel -
-Number -
-Positive Integer -
-0..1 -
-Depth of Linked Entity retrieval to apply. Default is 1. Only applicable if join parameter is “flat”, or “inline”. -
-lang -
-String -
-A natural language filter in the form of a IETF RFC 5646 [28] language code -
-0..1 -
-Language filter to be applied to the query (clause 4.15). -
-ordering -
-OrderingParams -
-See data type definition in clause 5.2.43 -
-0..1 -
-

When defined, the Entities returned in the payload shall be ordered according to the members defined.

-

This only applies if the operation is limited to the local scope.

-
-splitEntities -
-Boolean -
-default decided by implementation; it should be configurable. The parameter does not apply in case the parameter local is true or the query applies to a Snapshot -
-0..1 -
-If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally. -
-

5.2.24 EntityTypeList

-

This type represents the data needed to define the entity type list representation as mandated by clause 4.5.10.

-

The supported JSON members shall follow the requirements provided in Table 5.2.24‑1.

-
-

Table 5.2.24-1: NGSI-LD EntityTypeList data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-URI that is unique within the system scope. Identifier for the entity type list -
-type -
-String -
-It shall be equal to “EntityTypeList” -
-1 -
-JSON-LD @type -
-typeList -
-String[] -
-1 -
-List containing the entity type names -
-
-

5.2.25 EntityType

-

This type represents the data needed to define the elements of the detailed entity type list representation as mandated by clause 4.5.11.

-

The supported JSON members shall follow the requirements provided in Table 5.2.25‑1.

-
-

Table 5.2.25-1: NGSI-LD EntityType data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Fully Qualified Name (FQN) of the entity type being described -
-type -
-String -
-It shall be equal to “EntityType” -
-1 -
-JSON-LD @type -
-attributeNames -
-String[] -
-1 -
-List containing the names of attributes that instances of the entity type can have -
-
-typeName -
-String -
-1 -
-Name of the entity type, short name if contained in @context -
-
-

5.2.26 EntityTypeInfo

-

This type represents the data needed to define the detailed entity type information representation as mandated by clause 4.5.12.

-

The supported JSON members shall follow the requirements provided in Table 5.2.26‑1.

-
-

Table 5.2.26-1: NGSI-LD EntityTypeInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Fully Qualified Name (FQN) of the entity type being described -
-type -
-String -
-It shall be equal to “EntityTypeInfo” -
-1 -
-JSON-LD @type -
-attributeDetails -
-Attribute[] -
-See data type definition in clause 5.2.28. Attribute with only the elements “id”, “type”, “attributeName” and “attributeTypes” -
-1 -
-List of attributes that entity instances with the specified entity type can have -
-entityCount -
-Number -
-Unsigned integer -
-1 -
-Number of entity instances of this entity type -
-typeName -
-String -
-1 -
-Name of the entity type, short name if contained in @context -
-
-

5.2.27 AttributeList

-

This type represents the data needed to define the attribute list representation as mandated by clause 4.5.13.

-

The supported JSON members shall follow the requirements provided in Table 5.2.27‑1.

-
-

Table 5.2.27-1: NGSI-LD AttributeList data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-URI that is unique within the system scope. Identifier for the attribute list -
-type -
-String -
-It shall be equal to “AttributeList” -
-1 -
-JSON-LD @type -
-attributeList -
-String[] -
-1 -
-List containing the attribute names -
-
-

5.2.28 Attribute

-

This type represents the data needed to define the attribute information needed as:

-
-
    -
  • part of the entity type information representation as mandated by clause 4.5.12;
    • -
  • the detailed attribute list representation as mandated by clause 4.5.14;
    • -
  • the attribute information representation as mandated by clause 4.5.15.
    • -
-
-

The supported JSON members shall follow the requirements provided in Table 5.2.28‑1.

-
-

Table 5.2.28-1: NGSI-LD Attribute data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Full URI of attribute name -
-type -
-String -
-It shall be equal to “Attribute” -
-1 -
-JSON-LD @type -
-attributeName -
-String -
-1 -
-Name of the attribute, short name if contained in @context -
-
-attributeCount -
-Number -
-Unsigned integer -
-0..1 -
-Number of attribute instances with this attribute name -
-attributeTypes -
-String[] -
-0..1 -
-List of attribute types (e.g. Property, Relationship, GeoProperty) for which entity instances exist, which contain an attribute with this name -
-
-typeNames -
-String[] -
-0..1 -
-List of entity type names for which entity instances exist containing attributes that have the respective name -
-
-

5.2.29 Feature

-

This data type represents a spatially bounded Entity in GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members shall follow the requirements provided in Table 5.2.29‑1.

-
-

Table 5.2.29-1: Feature data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Entity ID -
-type -
-String -
-It shall be equal to “Feature” -
-1 -
-GeoJSON Type -
-geometry -
-GeoJSON Object -
-The value field from the matching GeoProperty (as specified in clause 4.5.16) or null -
-1 -
-null if no matching GeoProperty -
-properties -
-FeatureProperties -
-See data type definition -
-1 -
-List of attributes as mandated by clause 5.2.31 -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [26]) -
-

5.2.30 FeatureCollection

-

This data type represents a list of spatially bounded Entities in GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members shall follow the requirements provided in Table 5.2.30‑1.

-
-

Table 5.2.30-1: FeatureCollection data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “FeatureCollection” -
-1 -
-GeoJSON Type -
-features -
-Feature[] -
-See data type definition -
-1..N -
-In the case that no matches are found, features will be an empty array -
-@context -
-URI, JSON Object, or JSON Array -
-See [2], section 5.1. -
-0..1 -
-JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240 [26]) -
-

5.2.31 FeatureProperties

-

This data type represents the type and the associated attributes (Properties and Relationships) of an Entity in GeoJSON format.

-
-

Table 5.2.31-1: FeatureProperties data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String or String[] -
-Entity Type -
-1 -
-Entity Type (or JSON array, in case of Entities with multiple Entity Types). Both short hand string (type name) or URI are allowed. -
-<Property name> -
-Property or Property[], see note 1. -
-See data type definition in clause 5.2.5 -
-0..N -
-Property as mandated by clause 4.5.2. -
-GeoProperty or GeoProperty[], see note 1. -
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperty as mandated by clause 4.5.2. -
-LanguageProperty or LanguageProperty[], see note 1. -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperty as mandated by clause 4.5.18. -
-JsonProperty or JsonProperty[] see note 1. -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties as mandated by clause 4.5.24. -
-VocabProperty or VocabProperty[], see note 1. -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperty as mandated by clause 4.5.20. -
-ListProperty or ListProperty[], see note 1. -
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperty as mandated by clause 4.5.21. -
-<Relationship name> -
-Relationship or Relationship[], see note 2.2 -
-See data type definition in clause 5.2.6 -
-0..N -
-Relationship as mandated by clause 4.5.3. -
-ListRelationship or ListRelationship[], see note 2. -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationship as mandated by clause 4.5.22. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

5.2.32 LanguageProperty

-

This type represents the data needed to define a LanguageProperty as mandated by clause 4.5.18. Note that in case of concise representation, the type can be omitted (see clause 4.5.18.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.32‑1.

-
-

Table 5.2.32-1: NGSI-LD LanguageProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-string -
-It shall be equal to “LanguageProperty” -
-1 -
-Node type. -
-languageMap -
-JSON object -
-A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [28] language codes and whose values shall be JSON strings or arrays of JSON strings -
-1 -
-String Property Values defined in multiple natural languages. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the LanguageProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the LanguageProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-It shall be equal to “langString” (see note 1) -
-0..1 -
-The native JSON-LD @type for the languageMap attribute.It shall align with the RDF datatype [34]. -
-<Property name> -
-Property or Property[] (see note 2) -
-See datatype definition in clauses 5.2.5 -
-0..N -
-Properties of the LanguageProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 2)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the LanguageProperty. -
-LanguageProperty or LanguageProperty[] (see note 2) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the LanguageProperty. -
-JsonProperty or JsonProperty[] (see note 2) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the LanguageProperty. -
-VocabProperty or VocabProperty[] (see note 2) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the LanguageProperty. -
-

ListProperty

-

or ListProperty[] (see note 2)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the LanguageProperty. -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 3)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the LanguageProperty. -
-ListRelationship or ListRelationship[] (see note 3) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the LanguageProperty. -
-
-
-

NOTE 1:

-
-
-

The assigned @type for language tagged strings is datatype URI: http://www.w3.org/1999/02/22-rdf-syntax-ns#langString [34]

-
-
-
-
-

NOTE 2:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 3:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.32-2) of the LanguageProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.32-2: Output only members of the NGSI-LD LanguageProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of LanguageProperties -
-0..1 -
-URI uniquely identifying a LanguageProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousLanguageMap -
-JSON object -
-

A set of key-value pairs whose keys shall be strings representing IETF RFC 5646 [28] language codes and whose values shall be JSON strings.

-

Only used in Notifications, if the showChanges option is explicitly requested

-
-0..1 -
-Previous Language Property’s languageMap. -
-

5.2.33 EntitySelector

-

This type selects which entity or group of entities are queried or subscribed to by Context Consumers. Entities can be specified by their id, Entity Types or group of Entity IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]).

-

The JSON members shall follow the indications provided in Table 5.2.33‑1. id takes precedence over idPattern.

-
-

Table 5.2.33-1: EntitySelector data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-type -
-String -
-A valid type selection string as per clause 4.17. To indicate a request for all Entities (with implied local scope), “*” is also allowed as a value. -
-1 -
-Selector of Entity Type(s); If type is specified as “*”, implying local scope, local scope shall not be explicitly set to be false (clause 5.5.13) for the execution of the corresponding operation. -
-id -
-String or String[] -
-Valid URI(s) -
-0..1 -
-Entity identifier(s). -
-idPattern -
-String -
-Regular expression as per IEEE 1003.2™ [11] -
-0..1 -
-A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. -
-

5.2.34 RegistrationManagementInfo

-

This type represents the data to alter the default behaviour of a Context Broker when making a distributed operation request to a registered Context Source. The supported JSON members shall follow the indications provided in Table 5.2.34‑1. Brokers may override these recommendations.

-
-

Table 5.2.34-1: RegistrationManagementInfo data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-cacheDuration -
-String -
-String representing a duration in ISO 8601 [17] format -
-0..1 -
-

Minimal period of time which shall elapse between two consecutive context information consumption operations (as defined in clause 5.7) related to the same context data will occur.

-

If the cacheDurationlatency period has not been reached, a cached value for the entity or its attributes shall be returned where available.

-
-cooldown -
-Number -
-Greater than 0 -
-0..1 -
-

Minimum period of time in milliseconds which shall elapse before attempting to make a subsequent forwarded request to the same endpoint after failure.

-

If requests are received before the cooldown period has expired, a timeout error response for the registration is automatically returned.

-
-localOnly -
-Boolean -
-0..1 -
-

If localOnly=true then distributed operations associated to this Context Source Registration will act only on data held directly by the registered Context

-

Source itself (see clause 4.3.6.4).

-
-
-timeout -
-Number -
-Greater than 0 -
-0..1 -
-Maximum period of time in milliseconds which may elapse before a forwarded request is assumed to have failed. -
-

5.2.35 VocabProperty

-

This type represents the data needed to define a VocabProperty as mandated by clause 4.5.20. In case of concise representation, the type can be omitted (see clause 4.5.20.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.35‑1.

-
-

Table 5.2.35-1: NGSI-LD VocabProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “VocabProperty” -
-1 -
-Node type. -
-vocab -
-String or string[] -
-1 -
-String Values which shall be type coerced to URIs based on the supplied @context. -
-
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the VocabProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the VocabProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the vocab attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
-<Property name> -
-

Property

-

or Property[] (see note 1)

-
-See datatype definitions in clauses 5.2.5 -
-0..N -
-Properties of the VocabProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the VocabProperty. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the VocabProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the VocabProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the VocabProperty. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the VocabProperty. -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the VocabProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the VocabProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.35-2) of the VocabProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.35-2: Output only members of the NGSI-LD VocabProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of VocabProperties -
-0..1 -
-URI uniquely identifying a VocabProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousVocab -
-String or String[] -
-Only used in Notifications -
-0..1 -
-Previous VocabProperty’s vocab. -
-

5.2.36 ListProperty

-

This type represents the data needed to define a ListProperty as mandated by clause 4.5.21. Note that in case of concise representation, the type can be omitted (see clause 4.5.21.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.36‑1.

-
-

Table 5.2.36-1: NGSI-LD ListProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to“ListProperty” -
-1 -
-Node type. -
-valueList -
-An array of JSON values as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-1 -
-Ordered array of Property Values. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property list values -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the ListProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the ListProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the valueList attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
-<Property name> -
-

Property

-

or Property[] (see note 1)

-
-See datatype definition in clauses 5.2.5 -
-0..N -
-Properties of the ListProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the ListProperty. -
-

LanguageProperty

-

or LanguageProperty[] (see note 1)

-
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the ListProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the ListProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the ListProperty. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the ListProperty. -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the ListProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the ListProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.36-2) of the ListProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.36-2: Additional members of the NGSI-LD ListProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of ListProperties -
-0..1 -
-URI uniquely identifying a ListProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousValueList -
-An array of JSON values as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-0..1 -
-Ordered array of previous Property Values. -
-

5.2.37 ListRelationship

-

This type represents the data needed to define a ListRelationship as mandated by clause 4.5.22. Note that in case of concise representation, the type can be omitted (see clause 4.5.22.3) and the objectList may also be represented as an ordered array of Strings.

-

The supported JSON members shall follow the requirements provided in Table 5.2.37‑1.

-
-

Table 5.2.37-1: NGSI-LD ListRelationship data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “ListRelationship” -
-1 -
-Node type -
-objectList -
-

JSON Object[] or

-

String[]

-
-

In the normalized form, each array element holds a JSON object containing a single Attribute with a key called “object”and where the value is a valid URI.

-

In the concise form, each string in the array holds a valid URI

-
-1 -
-Ordered array of Relationship target objects. -
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of relationship list objects. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the ListRelationship. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the ListRelationship guaranteeing its integrity. -
-objectType -
-String or String[] -
-0..1 -
-

Node Type of the Relationship’s target object.

-

Both short hand string(s) (type name) or URI(s) are allowed.

-
-
-observedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-<Property name> -
-Property or Property[] (see note 1) -
-See datatype definition in clause 5.2.5 -
-0..N -
-Properties of the ListRelationship. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the ListRelationship. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the ListRelationship. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the ListProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the ListRelationship. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the ListRelationship. -
-<Relationship name> -
-Relationship or Relationship[] (see note 2) -
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the ListRelationship. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the ListRelationship. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.37-2) of the ListRelationship data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.37-2: Additional members of the NGSI-LD ListRelationship data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime (clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-entityList -
-Entity[] -
-

See datatype definition in clause 5.2.4

-

Only used in Linked Entity Retrieval, if the join=inline option is explicitly requested

-
-0..1 -
-An array of inline Entities obtained by Linked Entity retrieval, corresponding to the ListRelationship’s target objects See clause 4.5.23.2. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of ListRelationships -
-0..1 -
-URI uniquely identifying a ListRelationship instance as mandated by clause 4.5.8. -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousObjectList -
-

JSON Object[] or

-

String[]

-
-

In the normalized form, each array element holds a JSON object containing a containing a single Attribute with a key called “object”and where the value is a valid URI.

-

In the concise form, each string in the array holds a valid URI

-
-0..1 -
-Ordered array of previous Relationship target objects. -
-

5.2.38 JsonProperty

-

This type represents the data needed to define a JsonProperty as mandated by clause 4.5.24. In case of concise representation, the type can be omitted (see clause 4.5.24.3).

-

The supported JSON members shall follow the requirements provided in Table 5.2.38‑1.

-
-

Table 5.2.38-1: NGSI-LD JsonProperty data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-type -
-String -
-It shall be equal to “JsonProperty” -
-1 -
-Node type. -
-json -
-JSON -
-1 -
-Raw unexpandable JSON which shall not be interpreted as JSON-LD using the supplied @context. -
-
-datasetId -
-String -
-Valid URI -
-0..1 -
-It allows identifying a set or group of property values. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-0..1 -
-System temporal Property representing the expiration date for the storage of the JsonProperty. See clause 4.22 -
-ngsildproof -
-Property -
-Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed” as specified in [35]. The value of its “value” element shall be an object containing the W3C® Data integrity “proof” structure [35]. -
-0..1 -
-Cryptographic signature of the JsonProperty guaranteeing its integrity. -
-observedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-Timestamp. See clause 4.8. -
-valueType -
-String -
-0..1 -
-The native JSON-LD @type for the json attribute. A String Value which shall be type coerced to a URI based on the supplied @context. -
-
-<Property name> -
-

Property

-

or Property[] (see note 1)

-
-See datatype definitions in clauses 5.2.5 -
-0..N -
-Properties of the JsonProperty. -
-

GeoProperty

-

or GeoProperty[] (see note 1)

-
-See datatype definition in clause 5.2.7 -
-0..N -
-GeoProperties of the JsonProperty. -
-LanguageProperty or LanguageProperty[] (see note 1) -
-See datatype definition in clause 5.2.32 -
-0..N -
-LanguageProperties of the JsonProperty. -
-JsonProperty or JsonProperty[] (see note 1) -
-See datatype definition in clause 5.2.38 -
-0..N -
-JsonProperties of the JsonProperty. -
-VocabProperty or VocabProperty[] (see note 1) -
-See datatype definition in clause 5.2.35 -
-0..N -
-VocabProperties of the JSONPropertry. -
-

ListProperty

-

or ListProperty[] (see note 1)

-
-See datatype definition in clause 5.2.36 -
-0..N -
-ListProperties of the JsonProperty. -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 2)

-
-See datatype definition in clause 5.2.6 -
-0..N -
-Relationships of the JsonProperty. -
-ListRelationship or ListRelationship[] (see note 2) -
-See datatype definition in clause 5.2.37 -
-0..N -
-ListRelationships of the JsonProperty. -
-
-
-

NOTE 1:

-
-
-

For each Property (or subclass of Property ) identified by the same Property name, there can be one or more instances separated by datasetId.

-
-
-
-
-

NOTE 2:

-
-
-

For each Relationship (or subclass of Relationship ) identified by the same Relationship name, there can be one or more instances separated by datasetId.

-
-
-
-

The following output only members (defined by Table 5.2.38-2) of the JsonProperty data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.38-2: Output only members of the NGSI-LD JsonProperty data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-createdAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8. -
-deletedAt -
-String -
-

DateTime(clause 4.6.3)

-

It is only used in notifications reporting deletions

-
-0..1 -
-System generated deletion timestamp. See clause 4.8. -
-instanceId -
-String -
-Valid URI. Only used in temporal representation of JsonProperties -
-0..1 -
-URI uniquely identifying a JsonProperty instance as mandated by clause 4.5.7. -
-modifiedAt -
-String -
-DateTime(clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8. -
-previousJson -
-JSON -
-Only used in Notifications -
-0..1 -
-Previous JsonProperty’s json. -
-

5.2.39 EntityMap

-

This type represents the data needed to define an EntityMap as mandated by clause 4.5.25.

-

The supported JSON members shall follow the requirements provided in Table 5.2.39‑1.

-
-

Table 5.2.39-1: NGSI-LD EntityMap data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-EntityMap ID. -
-type -
-String -
-It shall be equal to “EntityMap” -
-1 -
-Node type. -
-expiresAt -
-String -
-DateTime (see clause 4.6.3) -
-1 -
-Expiration date for the EntityMap. -
-

The following output only members (defined by Table 5.2.39-2) of the EntityMap data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by ContextConsumers. In the event that they are provided in update operations NGSI-LD implementations shall ignore them.

-
-

Table 5.2.39-2: Additional members of the NGSI-LD EntityMap data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-entityMap -
-JSON -
-

A set of key-value pairs whose keys shall be strings representing Entity ids and whose values shall be an array holding every CSourceRegistration id which is relevant to the ongoing Context Information Consumption request (see clause 4.21).

-

The key “@none” shall be used to refer to an Entity that is held locally

-
-1 -
-System generated mapping of Entities to CSourceRegistrations. -
-linkedMaps -
-JSON -
-A set of key-value pairs whose keys shall be strings representing CSourceRegistration ids which are relevant to the ongoing Context Information request and whose values shall represent the associated EntityMap id used by the ContextSource. -
-1 -
-System generated mapping of Context CSourceRegistrations to a URI indicating which EntityMaps was used by the Context Source. -
-

5.2.40 Context Source Identity

-

This type represents the data uniquely identifying a Context Source, and if the Context Source supports multi-tenancy (see clause 4.14) uniquely identifying a Tenant within that Context Source.

-

The supported JSON members shall follow the requirements provided in Table 5.2.40‑1.

-
-

Table 5.2.40-1: Context Source Identity data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Context Source ID. -
-type -
-String -
-It shall be equal to “ContextSourceIdentity” -
-1 -
-JSON-LD @type. -
-contextSourceAlias -
-String -
-Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] -
-1 -
-

A unique id for a Context Source which can be used to identify loops.

-

In the multi-tenancy use case (see clause 4.14), this id shall be identify a specific Tenant within a registered Context Source.

-
-contextSourceUptime -
-String -
-String representing a duration in ISO 8601 [17] format -
-1 -
-Total Duration that the Context Source has been available. -
-contextSourceTimeAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Current time observed at the Context Source. Timestamp See clause 4.8. -
-contextSourceExtras -
-JSON -
-0..1 -
-Instance specific information relevant to the configuration of the Context Source itself in raw unexpandable JSON which shall not be interpreted as JSON-LD using the supplied @context. -
-
-

5.2.41 Snapshot

-

This type represents the data needed to create and manage a Snapshot.

-

The supported JSON members shall follow the requirements provided in table 5.2.41‑1.

-
-

Table 5.2.41-1: Snapshot data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-0..1 -
-System-generated at creation time, if it is not provided. It cannot be later modified in update operations. -
-type -
-String -
-It shall be equal to “Snapshot” -
-1 -
-JSON-LD @type -
-snapshotQueries -
-Query[] -
-List of Query (clause 5.2.23), where no Query no “temporalQ” element. -
-0..1 -
-Allows clients to specify a list of queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of “snapshotQueries” or “snapshotTemporalQueries” shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status or cloning the Snapshot. -
-snapshotTemporalQueries -
-Query[] -
-List of Query (clause 5.2.23), where each Query has “temporalQ” element. -
-0..1 -
-Allows clients to specify a list of temporal queries whose results are to be part of the Snapshot. This member can only be set when creating a snapshot, after that it becomes read-only. At least one of “snapshotQueries” or “snapshotTemporalQueries” shall be present when creating the snapshot and both shall be omitted when updating the Snapshot status. -
-snapshotLifetime -
-String -
-String representing a duration in ISO 8601 format [17] -
-0..1 -
-Suggested duration for which the requester wants the Snapshot to exist with respect to the current point in time. The actual expiresAt time of the Snapshot shall be set by the NGSI-LD system, possibly overriding the requested duration. -
-snapshotPriority -
-Number -
-Positive Integer between 1 and 10 -
-0..1 -
-The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It can be used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. -
-endpoint -
-String -
-Dereferenceable URI -
-0..1 -
-URI to which notifications regarding changes in the status of the Snapshot are to be sent. The information contained in the receiverInfo member shall be considered. -
-receiverInfo -
-KeyValuePair[] -
-0..1 -
-Generic {key, value} array to convey optional information to the receiver. -
-
-

The following output only members (defined by Table 5.2.41-2) of the Snapshot data structure are also defined. They are read-only and shall be generated by NGSI-LD implementations. They shall not be provided by Context Consumers. In the event that they are provided (in update or create operations) NGSI-LD implementations shall ignore them.

-
-

Table 5.2.41-2: Output only members of the Snapshot data type

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-snapshotStatus -
-String -
-

It shall be one of:

-

“preparing”,“success”,“partial”,

-

“failure”

-

or “empty”

-

The initial status shall be “preparing”.

-
-1 -
-Allows clients to check the status of the Snapshot. -
-snapshotQueriesDetails -
-ExecutionResultDetails[] -
-List of ExecutionResultDetails) -
-0..1 -
-List with one result per Snapshot query execution, in the same order as Snapshot queries -
-snapshotTemporalQueriesDetails -
-ExecutionResultDetails[] -
-List of ExecutionResultDetails) -
-0..1 -
-List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries -
-createdAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated creation timestamp. See clause 4.8 -
-modifiedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated last modification timestamp. See clause 4.8 -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-

Expiration time for the snapshot – it is possible to indirectly update the member by updating snapshotLifetime.

-

See clause 4.8

-
-lastUsedAt -
-String -
-DateTime (clause 4.6.3) -
-0..1 -
-System generated timestamp identifying the point in time when the snapshot was most recently used. It is initialized at creation time. See clause 4.8 -
-

5.2.42 ExecutionResultDetails

-

This type represents the details of the result of execution a request, e.g. a Query.

-

The supported JSON members shall follow the requirements provided in table 5.2.42‑1.

-
-

Table 5.2.42-1: ExecutionResultDetails data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-problemDetails -
-@JSON -
-ProblemDetails (see IETF RFC 7807 [10]) -
-0..1 -
-Provides more details regarding the result status, especially when reporting an error. -
-resultStatus -
-String -
-

It shall be one of:

-

“success”,

-

“failure”

-

or “empty”

-
-1 -
-Describes the status of the result. “failure”, if an error is reported, “success”in case of a non-empty result and “empty” otherwise. -
-

5.2.43 OrderingParams

-

This datatype represents the parameters that convey the definition used whilst ordering Entities.

-

The supported JSON members shall follow the requirements provided in Table 5.2.43‑1.

-
-

Table 5.2.43-1: OrderingParams data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Description -
-collation -
-String -
-An ICU collation (see IETF RFC 6067 [36]), -
-0..1 -
-The Entities returned in the payload shall be ordered according to the collation given. By default it shall be ICU “root” collation order (“und-x-icu”) -
-coordinates -
-JSON Array -
-A JSON Array coherent with the geometry type as per IETF RFC 7946 [8] -
-

0..1

-

It shall be one if orderBy uses order by distance

-
-Coordinates of a Geometry used when sorting by distance -
-geometry -
-String -
-A valid GeoJSON [8] geometry type excepting GeometryCollection -
-0..1 -
-The type of geometry whose coordinates are used when sorting by distance. By default, it shall be a “Point” geometry -
-orderBy -
-String[] -
-Each String is an Entity member (“id”, “type”, “scope” or an Attribute name) appended with an optional sorting style (“asc”, “desc”, “dist-asc”, “dist-desc”)as per clause 4.23 -
-1 -
-When defined, the Entities returned in the payload shall be ordered according to members defined. -
-

5.2.44 AggregationParams

-

This datatype represents the parameters required for supporting aggregation methods in temporal requests.

-

The supported JSON members shall follow the requirements provided in Table 5.2.44‑1.

- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restriction -
-Cardinality -
-Remarks -
-aggrMethods -
-Comma separated list of strings -
-Each String represents an aggregation method, as defined by clause 4.5.19. -
-1 -
-- -
-aggrPeriodDuration -
-String -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19.

-

If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-
-0..1 -
-- -
-
-

Table 5.2.44-1: AggregationParams data type definition

-
-

5.3 Notification data types

-

5.3.1 Notification

-

This datatype represents the parameters that allow building a notification to be sent to a subscriber. How to build this notification is detailed in clause 5.8.6.

-

The supported JSON members shall follow the indications provided in Table 5.3.1‑1.

-
-

Table 5.3.1-1: Notification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-id -
-String -
-Valid URI -
-1 -
-Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. -
-type -
-String -
-It shall be equal to “Notification” -
-1 -
-JSON-LD @type. -
-data -
-NGSI-LD Entity[] or FeatureCollection -
-1 -
-

The content of the notification as NGSI-LD Entities. See clause 5.2.4.

-

If the notification has been triggered from a Subscription that has the notification.

-

endpoint.accept field set to application/geo+jsonthen data is returned as a FeatureCollection. In this case, if the notification.endpoint.receiverInfocontains the key “Prefer” and it is set to the value “body=json”, then the FeatureCollection will not contain an @context field.

-

If endpoint.accept is not set or holds another value then Entity[] is returned.

-
-
-notifiedAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Timestamp corresponding to the instant when the notification was generated by the system. -
-subscriptionId -
-String -
-Valid URI -
-1 -
-Identifier of the subscription that originated the notification. -
-

5.3.2 CSourceNotification

-

This datatype represents the parameters that allow building a Context Source Notification to be sent to a subscriber. How to build this notification is detailed in clause 5.11.7.

-

The supported JSON members shall follow the indications provided in Table 5.3.2‑1.

-
-

Table 5.3.2-1: CSourceNotification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameData TypeRestrictionsCardinalityDescription

{TAL}

-

id

{TAL}

-

String

{TAL}

-

Valid URI

{TAL}

-

1

{TAL}

-

CSource notification identifier (JSON-LD @id).

{TAL}

-

type

{TAL}

-

String

{TAL}

-

It shall be equal to “ContextSourceNotification”

{TAL}

-

1

{TAL}

-

JSON-LD @type.

{TAL}

-

data

{TAL}

-

CSource

-

Registration[]

{TAL}

-

1

{TAL}

-

The content of the notification as NGSI-LD CSourceRegistrations. See clause 5.2.9.

{TAL}

-

notifiedAt

{TAL}

-

String

{TAL}

-

DateTime (see clause 4.6.3)

{TAL}

-

1

{TAL}

-

Timestamp corresponding to the instant when the notification was generated by the system.

{TAL}

-

subscriptionId

{TAL}

-

String

{TAL}

-

Valid URI

{TAL}

-

1

{TAL}

-

Identifier of the subscription that originated the notification.

{TAL}

-

triggerReason

{TAL}

-

String

{TAL}

-

TriggerReasonEnumeration (see clause 5.3.3)

{TAL}

-

1

{TAL}

-

Indicates whether the CSources in the CSourceRegistration(s) in data are newly matching (initial notification or creation), have been updated (but still match) or do not match any longer.

-

5.3.3 TriggerReasonEnumeration

-

The enumeration can take one of the following values:

-
-
    -
  • “newlyMatching” - describes the case that the notified Context Source Registration(s) newly match(es) the identified subscription. This value is used in the first notification and whenever a new Context Source Registration matching the Subscription has been registered, or an existing Context Source Registration that did not match before has been updated in such a way that it matches now.
    • -
  • “updated” - describes the case that the notified Context Source Registration that was part of a previous notification has been updated, but still matches the Subscription.
    • -
  • “noLongerMatching” - describes the case that the notified Context Source Registration that was part of a previous notification no longer matches the Subscription, i.e. as a result of an update or because it was deleted.
    • -
-
-

5.3.4 SnapshotNotification

-

This datatype represents the parameters that allow building a snapshot notification to be sent to a subscriber. How to build this notification is detailed in .

-

The supported JSON members shall follow the indications provided in Table 5.3.4‑1.

-
-

Table 5.3.4-1: SnapshotNotification data type definition

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Restrictions -
-Cardinality -
-Description -
-Id -
-String -
-Valid URI -
-1 -
-Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. -
-type -
-String -
-It shall be equal to “SnapshotNotification” -
-1 -
-JSON-LD @type. -
-expiresAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Expiration time for the snapshot – if expiresAt is before notifiedAt, the notification indicates that the snapshot has been deleted. In this case, snapshotReady shall be set to false. -
-notifiedAt -
-String -
-DateTime (clause 4.6.3) -
-1 -
-Timestamp corresponding to the instant when the notification was generated by the system. -
-snapshotId -
-String -
-Valid URI -
-1 -
-Identifier of the snapshot whose status change triggered the notification. -
-snapshotPriority -
-Number -
-Positive Integer between 1 and 10 -
-1 -
-The priority of a snapshot ranges from 1 (minimum) to 10 (maximum) with 5 being the default priority. It is used when deciding which snapshot is to be deleted if an implementation determines that it is low on resources. -
-snapshotQueriesDetails -
-ExecutionResultDetails[] -
-List of ExecutionResultDetails) -
-0..1 -
-List with one result per Snapshot query execution, in the same order as Snapshot queries -
-snapshotStatus -
-String -
-

It shall be one of:

-

“success”,“partial”,

-

“failure”

-

or “empty”

-
-1 -
-Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying. -
-temporalSnapshotQueriesDetails -
-ExecutionResultDetails[] -
-List of ExecutionResultDetails) -
-0..1 -
-List with one result per temproal Snapshot query execution, in the same order as temporal Snapshot queries -
-

5.4 NGSI-LD Fragments

-

When updating NGSI-LD elements (Entities, Attributes, Context Source Registrations or Subscriptions) it is necessary to have a means of describing a set of modifications to their content.

-

An NGSI-LD Fragment is a JSON Merge Patch document [16] and [i.10] which describes changes to be made to a target JSON-LD document using a syntax that closely mimics the document being modified.

-

An NGSI-LD Fragment is a JSON-LD Object which shall include the following members:

-
-
    -
  • id (optional for certain bindings where it can be determined from the operation signature). It shall be equal to the id of the target (mutated) NGSI-LD element. Attribute Fragments do not contain explicit ids.
    • -
  • type (optional for certain bindings where it can be determined from the operation signature). It shall contain the Type name(s) of the target NGSI-LD element.
    • -
  • A member (following the same data representation and nesting structure) for each new member to be added to the target NGSI-LD element.
    • -
  • A member (following the same data representation and nesting structure) for each new member to be modified in the target NGSI-LD element, which value shall correspond to the new member value to be given.
    • -
-
-
-
-

EXAMPLE 1:

-
-
-

The following Subscription Fragment allows the modification of a Subscription by changing its endpoint’s URI:

-
{
-    "id": "urn:ngsi-ld:Subscription:MySubscription",
-"type": "Subscription",
-"endpoint": {
-    "uri": "http://example.org/newNotificationEndPoint"
-}
-}
-
-
-
-
    -
  • A member (following the same data representation and nesting structure) with value equal to an NGSI-LD Null shall cause for the member to be removed from the target NGSI-LD element.
    • -
-
-
-
-

EXAMPLE 2:

-
-
-

The following NGSI-LD Fragment allows the modification of an Entity by changing its batteryLevel Attribute, updating the observedAt sub-Attribute, removing the providedBy sub-Attribute and removing the uncharged Attribute from the Entity:

-
{
-"id": "urn:ngsi-ld:TemperatureSensor:001",
-"type": "TemperatureSensor",
-"batteryLevel": {
-"type": "Property",
-"value": 7,
-"observedAt": "2022-03-14T12:51:02.000Z",
-"providedBy": "urn:ngsi-ld:null"
-},
-"uncharged" : {
-"type": "Property",
-"value": "urn:ngsi-ld:null"
-}
-}
-
-
-

5.5 Common Behaviours

-

5.5.1 Introduction

-

This clause defines common behaviours for the API operations.

-

When comparing URIs, implementations shall follow the recommendations of IETF RFC 3986 [5], section 6.

-

5.5.2 Error types

-

Table 5.5.2‑1 details a list of error types defined by NGSI-LD. The particular conditions under which error type shall be raised are defined when describing each operation supported by the API.

-
-

Table 5.5.2-1: Error types in NGSI-LD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Error Type -
-Description -
-https://uri.etsi.org/ngsi-ld/errors/AlreadyExists -
-The referred element already exists -
-https://uri.etsi.org/ngsi-ld/errors/BadRequestData -
-The request includes input data which does not meet the requirements of the operation -
-https://uri.etsi.org/ngsi-ld/errors/Conflict -
-The operation conflicts with the current state of the system -
-https://uri.etsi.org/ngsi-ld/errors/InternalError -
-There has been an error during the operation execution -
-https://uri.etsi.org/ngsi-ld/errors/InvalidRequest -
-The request associated to the operation is syntactically invalid or includes wrong content -
-https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable -
-A remote JSON-LD @context referenced in a request cannot be retrieved by the NGSI-LD Broker and expansion or compaction cannot be performed -
-https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport -
-The NGSI-LD API implementation does not support multiple tenants -
-https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant -
-The addressed tenant does not exist -
-https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported -
-The operation is not supported -
-https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound -
-The referred resource has not been found -
-https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery -
-The query associated to the operation is too complex and cannot be resolved -
-https://uri.etsi.org/ngsi-ld/errors/TooManyResults -
-The query associated to the operation is producing so many results that can exhaust client or server resources. It should be made more restrictive -
-

5.5.3 Error response payload body

-

When reporting errors back to clients, NGSI-LD implementations shall generate a JSON object in accordance with IETF RFC 7807 [10], section 3.1, including, at least the following terms:

-
-
    -
  • type: Error type as per clause 5.5.2.
    • -
  • title: Error title which shall be a short string summarizing the error.
    • -
  • detail: A detailed message that should convey enough information about the error.
    • -
-
-

Even though IETF RFC 7807 [10] defines a specific MIME type for error payloads, NGSI-LD implementations shall use the standard JSON MIME type (“application/json”) when reporting errors, so that old clients or existing tools are not broken.

-
-
-

EXAMPLE:

-
-
-
{
-"type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound",
-"title": "Resource not found.",
-"detail": "urn:ngsi-ld:Device:widget001 was not found",
-"status": 404,
-"instance": "urn:ngsi-ld:Device:widget001"
-}
-
-
-

5.5.4 General NGSI-LD validation

-

All the operations that take a JSON-LD document as input shall process such JSON-LD document as follows:

-
-
    -
  • If the request payload body is not a valid JSON document then an error of type InvalidRequest shall be raised.
    • -
  • If the data included by the JSON-LD document is not syntactically correct, according to the @context or the API data type definitions, then an error of type BadRequestData shall be raised.
    • -
  • A Context Producer may supply an additional hint regarding the overall validity of the payload body and the version of the NGSI-LD specification that the API datatype definitions conform to. When receiving such an annotated context production request, a Context Brokerthat it is only partially capable of interpreting the datatypes held within the payload body may use this information to amend the data held within the payload through applying fallbacks (see clause 4.3.6.8) prior to validation.
    • -
  • Any attempt to use “urn:ngsi-ld:null” as a first level member value (“<key>”: “urn:ngsi-ld:null”), with the exception of NGSI-LD Fragments (see clause 5.4) used in partial update and merge operations (as mandated by clause 5.5.8 and clause 5.5.12) or to represent deleted Properties in concise representation as part of notifications, shall result in an error of type BadRequestData.
    • -
  • Any attempt to use “urn:ngsi-ld:null“ as the right-hand side of value in a Property, as the right-hand side of object in a Relationship or to use {“@none”: “urn:ngsi-ld:null”}as the right-hand side of languageMap, with the exception of NGSI-LD Fragments (see clause 5.4) used in update and merge operations (as mandated by clause 5.5.8 and clause 5.5.12) and the representation of deleted Properties, Relationships or Language Properties in notifications and the temporal evolution, shall result in an error of type BadRequestData.
    • -
  • Any attempt to use “urn:ngsi-ld:null“ as the value of a key value pair within a JSON object, which is the right-hand side of the value of a Property, with the exception of NGSI-LD Fragments used in merge operations (see clause 5.5.12), shall result in an error of type BadRequestData.
    • -
-
-

5.5.5 Default @context assignment

-

If the input provided by an API client does not include any @context, then the implementation shall at minimum assign the Core @context to such an input. In addition, the Context Broker implementation may allow configuring a default user @context (with default terms), to be used when no user @context is provided. The Core @context shall always take precedence.

-

5.5.6 Operation execution and generic error handling

-

When executing an operation if an unexpected error happens and the operation cannot be completed, implementations shall raise an error of type InternalError. This includes, as well, situations such as database timeouts, etc.

-

If the NGSI-LD endpoint is not capable of executing the requested operation, an error of type OperationNotSupported shall be raised. This may happen in a distributed architecture where a Context Broker might not be able to store Entities (only to forward queries to Context Sources), and as a result, certain operations such as “Create Entity” might not be supported.

-

When a query operation is so complex that cannot be resolved by an NGSI-LD system, implementations shall raise an error of type TooComplexQuery.

-

When a query operation is producing so many results that can potentially exhaust client or server resources, or it can be just impractical to be managed, implementations shall raise an error of type TooManyResults. The threshold conditions used as criteria to raise such error is up to each implementation.

-

When a remote JSON-LD @context referenced by an incoming request is not available, implementations shall raise an error of type LdContextNotAvailable. If the remote JSON-LD @context is invalid, implementations shall raise an error of type BadRequestData.

-

5.5.7 Term to URI expansion or compaction

-

NGSI-LD API operations allow clients to use short-hand strings as non-qualified names, particularly for Property, Relationship or Type names and VocabProperty values. For instance, an API client can refer to the term “Vehicle” as a non-qualified type name. When executing API update-related operations, NGSI-LD systems shall expand terms to URIs, in order to obtain and store Fully Qualified Names. Likewise, when executing query-related operations, NGSI-LD systems shall compact URIs (Fully Qualified Names) to short terms in order to provide short-hand strings to context consumers.

-

The term to URI expansion or compaction shall be performed using a @context as described by the JSON-LD specification [2] (section 5.1), and in clause 4.4. In the absence of a user @context, the term expansion or compaction shall be performed according to clause 5.5.5.

-

For the avoidance of doubt, the @context used to perform compaction or expansion of terms shall be the one provided by each API call (or the default @context in its absence), and not any other @context which might have been supplied previously. For instance, when performing “Query Entity” operations (clause 5.7.2), the @context used to perform URI expansion and compaction shall be the one provided by the request.

-

In case of HTTP binding via GET (clause 6.4.3.2) of the “Query Entity” operation, this means using the JSON-LD Link Header as described by the JSON-LD specification [2], section 6.2. In case of HTTP binding via POST (clause 6.23.3.1), of the “Query Entity” operation, this means giving the @context either via Link Header or within the payload body, depending on the Content-Type Header being “application/json” or “application/ld+json”, respectively.

-

It is important to warn users that updating a @context could lead to behaviour that might be perceived as inconsistent. If, for instance, a fully qualified name that qualified a given short-hand name is changed, from that moment onwards, the short-hand name is referencing a different Attribute. This will effectively change the results of queries that use the given short name, possibly not giving back anymore the expected set of results.

-

Moreover, this user @context shall not:

-
-
    -
  • Contain JSON-LD Scoped Contexts (see [2], section 4.1.8).
    • -
  • Be embedded into NGSI-LD Attributes, i.e. there cannot be parts of the user @context other than at the top level of the NGSI-LD document.
    • -
-
-

Parts of user @context that are not following the two points above should result in an error of type BadRequestData, because JSON-LD Scoped Contexts and nested embedded @context could be used to modify terms defined in the Core @context or to reshape NGSI-LD Elements during the expansion of terms.

-

As the Core @context is protected and cannot be overridden, when performing term to URI expansion or compaction, implementations shall always consider the Core @context as having absolute precedence, regardless of the position of the Core @context in the @context array of elements. Nonetheless, NGSI-LD data providers may use appropriate term prefixing to ensure that a proper term to URI expansion or compaction is performed.

-

At compaction time, in the event that no matching term is found in the current @context, implementations shall render Fully Qualified Names.

-
-
-

EXAMPLE:

-
-
-

An entity of type “Vehicle” bound to a certain @context , C, will match a query by “Vehicle” type if and only if the supplied query @context , Q, maps the term “Vehicle” to the same URI as C.

-
-
-

Note that the JsonProperty is designed to hold native JSON values which are by definition not available for expansion and compaction via an @context. Therefore the given short-hand name is always used for accessing JSON keys within a JsonProperty json element.

-

5.5.8 Partial Update Patch Behaviour

-

The Partial Update Patch procedure modifies an existing NGSI-LD element by overwriting the data at the Attribute level, replacing it with the data provided in the NGSI-LD Fragment.

-

When updating NGSI-LD elements (Entities, Context Source Registrations or Context Subscriptions) using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element.

-

With respect to update operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [16]), in order to observe the name to URI expansion rules and the JSON-LD null processing):

-
-
    -
  • For each member of the Fragment perform the term to URI expansion.
    • -
  • If the provided Fragment (a JSON Merge Patch document) contains members that do not appear within the target (their URIs do not match), those members are added to the target.
    • -
  • For each member of the Fragment contained by the target, the target member value is replaced by the value given in the Fragment. In the case of a member representing a reified Property or Relationship including a datasetId, such member is only replaced if the datasetId is the same, otherwise the member of the Fragment is added as a new instance to the target. If no datasetId is present, the default Attribute instance is targeted and replaced if present and otherwise added. In case of a member type (of an entity) in Entity Fragments, all included Entity Types are added, if they are not already contained in the type member of the target.
    • -
  • For each member of the Fragment, whose value is an NGSI-LD Null, contained by the target, the target member is deleted. In the case of deleting a specific Attribute instance with a datasetId, the handling shall be in accordance with the description found in clause 5.6.5. A datasetId cannot be deleted by setting it to the value “urn:ngsi-ld:null”.
    • -
-
-
-
-

EXAMPLE 1:

-
-
-

Given an Entity containing the following Property:

-
{
-"temperature": {
-"type": "Property",
-"value": 25,
-"unitCode": "CEL"
-"observedAt": "2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"type": "Property",
-"value": 100,
-"observedAt": "2022-03-14T13:00:00.000Z" 
-}
-
{
-"temperature": {
-"type": "Property",
-"value": 100,
-"unitCode": "CEL"
-"observedAt": "2022-03-14T13:00:00.000Z"
-}
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

Given an Entity containing the following Property :

-
{
-"temperature": {
-"type": "Property",
-"value": 25,
-"unitCode": "CEL"
-"observedAt": "2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"temperature": {
-"type": "Property",
-"value": 100,
-"observedAt": "2022-03-14T13:00:00.000Z"
-}
-}
-
{
-"temperature": {
-"type": "Property",
-"value": 100,
-"observedAt": "2022-03-14T13:00:00.000Z"
-}
-}
-
-
-
-
-

EXAMPLE 3:

-
-
-

Given an Entity containing the following Property :

-
{
-"temperature": {
-"type": "Property",
-"value": 25,
-"unitCode": "CEL"
-"observedAt": "2022-03-14T01:59:26.535Z"
-}
-}
-
{
-"temperature": {
-"type": "Property",
-"value":
-}
-}
-
-
-

5.5.9 Pagination Behaviour

-

5.5.9.1 General Pagination Behaviour

-

When resolving NGSI-LD Query operations, NGSI-LD Systems shall exhibit the behaviour described by the present clause:

-
-
    -
  • Let Md be equal to the default maximum number of NGSI-LD Elements to be retrieved by the API during each query pagination iteration, as defined by the NGSI-LD implementation.
    • -
  • Let Mc be equal to the maximum number of NGSI-LD Elements to be retrieved as requested by the NGSI-LD Client. If Mc is undefined then it shall be equal to Md.
    • -
  • Let L be the maximum number of NGSI-LD Elements to be retrieved by the API during each query pagination iteration. L shall be equal to Mc.
    • -
  • During query execution and for each pagination iteration, the query resolution mechanisms of the NGSI-LD System shall ensure that only up to a maximum of L NGSI-LD Elements are retrieved and returned to the NGSI-LD client, i.e. the maximum page size per iteration shall not overpass L. Nonetheless, implementations shall take care of not overpassing a maximum size of response payload body, which, in practice, implies that, under certain circumstances, the number of Elements retrieved per page can be lower than L.
    • -
  • After the retrieval of each page (containing at most L NGSI-LD Elements) implementations shall check whether there are pending NGSI-LD Elements to be retrieved in the context of the current query. If that is the case, implementations shall flag NGSI-LD Clients of the existence of such NGSI-LD Elements. Ultimately, the flagging mechanisms used shall depend on each API binding but shall be present as mandated by the present clause.
    • -
  • When flagging the existence of additional NGSI-LD Elements (pages) pending to be retrieved, generally, implementations shall provide NGSI-LD Clients pointers to get access to both the following page of NGSI-LD Elements and the previous one, according to the current pagination iteration.
    • -
  • The pointer to the previous page of NGSI-LD Elements shall be included for all pagination iterations excepting the first one, as, obviously, there will be no previous NGSI-LD Elements.
    • -
  • When the last page of NGSI-LD Elements is reached, only the pointer to the previous page shall be provided to NGSI-LD Clients, so that they can detect that no more NGSI-LD Elements are available.
    • -
  • The pointers to NGSI-LD Elements shall contain all the parameters needed to allow NGSI-LD Clients to retrieve the next and previous page, without further interactions with the API.
    • -
-
-

While iterating over a set of pages, there might be changes in the target result set, due to additions or removals of NGSI-LD Elements occurring in between. Implementations may detect those situations and may warn NGSI-LD Clients appropriately. During pagination, the same @context shall be used. An attempt to use a different @context should result in an BadRequestData error.

-

5.5.9.2 Pagination option using limit and offset

-

The general pagination behaviour described in clause 5.5.9.1 only requires pointers to the following and previous pages, which can be implemented in a completely opaque way. Pagination may also be implemented in a transparent way, giving the Context Consumer more control over the process. In this case, the parameters limit and offset should be used, allowing the Context Consumer to adapt the size of the page using limit and jump to a desired set of elements in the results using offset.

-

5.5.9.3 Pagination with Entity maps

-

In the case of queries based on Entity maps, the set of Entities considered for the result is fixed with the initial query creating the Entity map. However, the Entity information itself can be dynamic, so filters shall be rechecked before returning results. In the case of split Entities, the Entities in the Entity map can only be considered as candidate Entities, since, at the time of Entity map creation, the Entities have not been aggregated and thus the filters could not be applied. This can only be done when preparing a page for pagination. Thus, Entities not or no longer fitting the query shall be removed from the Entity map during pagination. Pages shall always be filled to the maximum, as long as Entities are available. When using the previous link, the set of Entities on the previous page may not be the same as before, due to dynamic changes resulting in Entities no longer fulfilling the filter criteria of the query. As a result, the first page when going backward, and the last page, when going forward, may have less than the maximum number of Entities.

-

5.5.10 Multi-Tenant Behaviour

-

If a Tenant is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specified Tenant. If no Tenant is specified, the operation shall apply to the implicitly existing default Tenant. If a Tenant is explicitly specified, but the system implementing the NGSI-LD API does not support multi-tenancy, an error of type NoMultiTenantSupport should be raised.

-

In case an operation applies to a Tenant, this information shall also be provided in the response to the operation. This also applies to notifications sent as a result of subscriptions (clauses 5.8 and 5.11).

-

A Tenant is represented in form of a String. How the Tenant is specified for an API operation is protocol binding specific. How Tenants are created, is implementation-specific.

-

One implementation option is to support the implicit creation of Tenants. This means that a Tenant is implicitly created when an NGSI-LD operation for creating information targets a new Tenant; this is the case for:

-
- -
-

All other NGSI-LD operations, e.g. for retrieving, updating, appending or deleting information that target a non-existing Tenant should raise an error of type NonexistentTenant.

-

If the system implementing the NGSI-LD API does not support multiple Tenants, the attempt to register a Context Source with Tenant information in the Context Source Registration should also result in an error of type NoMultiTenantSupport.

-

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

-

5.5.11.0 Foreword

-

The following operations operate on an array of entities (as input payload):

-
- -
-

It is allowed for such an input Entity array to contain more than one instance of the same entity (those instances have identical ids).

-

In order for such a request to be correctly handled, those instances that have the same id are processed by the Broker in the order they have in the array: the higher the index in the array, the later it will be processed. If the order is altered, the outcome may be altered.

-

All Entities and Attributes in the batch will get the same modifiedAt timestamp, so it makes sense to distinguish them via the observedAt temporal property.

-

Implementations shall treat the entity instances as if they had all arrived in separate requests.

-

The following clauses specify the behaviour in each case.

-

5.5.11.1 Batch Entity Creation case

-

The first occurrence of an entity in the input array (the oldest one) is used for the creation of the entity. Any subsequent instance of the same entity is reported as an error (entity already exists) in the response.

-

5.5.11.2 Batch Entity Creation or Update (Upsert) case

-

This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing entities, while the optional behaviour is to update already existing entities. Non existing entities are created in both modes.

-

If the entity does not yet exist, the first occurrence of an entity is used to create the entity, and subsequent instances of that same entity are used to either replace (default behaviour) or to update (optional behaviour) the entity. These replace or update operations shall be done in chronological order.

-

Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in clause 4.3.1). For Temporal Evolution of Entities (as defined in clause 4.3.1), all entity instances shall be taken into account, in the correct order.

-

5.5.11.3 Batch Entity Update case

-

This operation has two modes of operation, with an optional flag to select between the two. The default behaviour is to replace any already existing attributes of the entities, while the optional behaviour is to preserve already existing attributes of the entities.

-

Brokers shall send separate notifications for each individual update, taking throttling into account.

-

5.5.11.4 Batch Entity Delete case

-

The Batch Entity Delete operation has as input an array of Entity IDs, for the entities to be deleted. If an Entity ID is replicated in the array, the first occurrence will delete the entity, while subsequent occurrences of the same Entity ID will provoke an error in the response (entity does not exist).

-

5.5.11.5 Batch Entity Merge case

-

The Batch Entity Merge operation has as input an array of Entity IDs, for the entities to be merged. If an Entity ID is replicated in the array, these merge operations shall be done in chronological order. Only the entity resulting from merging all of the entity instances, in the correct order, is maintained in the current state (as defined in clause 4.3.1). For Temporal Evolution of Entities (as defined in clause 4.3.1), all entity instances shall be taken into account, in the correct order.

-

5.5.12 Merge Patch Behaviour

-

The merge patch procedure modifies an existing NGSI-LD element by applying the set of changes found in an NGSI-LD Fragment data to the target resource. Unlike the partial update patch behaviour (described in clause 5.5.8), which replaces the complete element on the first level, e.g. a whole Attribute, the procedure described in this clause merges the provided information with the existing information up to an arbitrary depth, e.g. including going into JSON objects representing a Property value.

-

When merging NGSI-LD Entities using NGSI-LD Fragments, implementations shall determine the exact set of changes being requested by comparing the content of the provided Fragment (patch) against the current content (a JSON-LD object) of the target element.

-

With respect to merge operations, implementations shall perform an algorithm equivalent to the one described below (adapted from IETF RFC 7396 [16], in order to observe the name to URI expansion rules and JSON-LD null processing):

-
-
    -
  • For each member of the Fragment perform the term to URI expansion.
    • -
  • If the provided Fragment (a JSON Merge Patch document) contains members that do not appear within the target (their URIs do not match), those members are added to the target.
    • -
  • For each member of the Fragment contained by the target, the target member value is merged with the value given in the Fragment. NGSI-LD Nulls within the Fragment are given special meaning to indicate the removal of existing values within the target member value. In the case of a member representing a reified Property or Relationship including a datasetId, such member is only updated if the datasetId is the same, otherwise the member of the Fragment is added as a new instance to the target. If no datasetId is present, the default Attribute instance is targeted and merged if present and otherwise added. In case of a member type (of an Entity) in Entity Fragments, all included Entity Types are added, if they are not already contained in the type member of the target.
    • -
  • For each member of the Fragment, whose value is an NGSI-LD Null, contained by the target, the target member is removed. In the case of deleting a specific Attribute instance with a datasetId, the handling shall be according to the description in clause 5.6.5. A datasetId cannot be deleted by setting it to the value “urn:ngsi-ld:null”.
    • -
-
-
-
-

EXAMPLE 1:

-
-
-

Given an Entity containing the following Property :

-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 25,
-    "unitCode": "CEL"
-    "observedAt": "2022-03-14T01:59:26.535Z"
-  }
-}
-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 100,
-    "observedAt": "2022-03-14T13:00:00.000Z"
-  }
-}
-
{
-  "temperature": {
-    "type" : "Property",
-    "value" : 100,
-    "unitCode": "CEL",
-    "observedAt": "2022-03-14T13:00:00.000Z"
-  }
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

Given an Entity containing the following Property :

-
{
-  "address": {
-    "type" : "Property",
-    "value" : {
-          "street": "Straße des 17. Juni",
-          "city": "Berlin",
-          "country": "Germany"
-    }
-  }
-}
-
{
-  "address": {
-    "type" : "Property",
-    "value" : {
-          "street": "Pariser Platz",
-          "country": "urn:ngsi-ld:null"
-    }
-  }
-}
-
{
-  "address": {
-    "type" : "Property",
-    "value": {
-          "street": "Pariser Platz",
-          "city": "Berlin"
-    }
-}
-
-
-

5.5.13 Limiting operations to local scope

-

The API provides a binding-specific mechanism to limit the execution of operations to a local scope, i.e. to only execute it based on information available in the Context Source or Context Brokerdirectly targeted by the request. This enables limiting cascading distributed operations (clause 4.3.6.4) and, in some cases, also enables broader local operations, e.g. pertaining to all entities, which would be too expensive in the distributed case.

-

The localOnlymember in the Subscription (clause 5.5.12) requests that the subscription only matches Entities stored locally.

-

The localOnly member in the RegistrationManagementInfo (clause 5.2.34) of a Context Source Registration request that, when contacting the registered Context Source, a local scope shall be specified. Thus, the registered Context Source only provides its local information, not information from further Context Sources in its own Context Registry.

-

If the request limits the execution of the operation to the local scope, Context Source Registrations from the Context Registry will not be used.

-

Operations on a Snapshot (see clause 5.5.15) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations.

-

5.5.14 Distributed Transactional Behaviour

-

The following operations may occur as part of a distributed transactional request:

-
- -
-

In the case that a client wishes to indicate to a Context Broker that a request is part of a unitary sequence of requests, the Context Broker shall create and cache an EntityMap for future use and should return the location of said EntityMap in a specific field. The caching strategy and expiry time shall take into account a suggested expiry time, if present, and depend on implementation specific configurations. Context Sources should indicate that they do not support EntityMaps, through declining to return the location of an EntityMap when requested to do so.

-

If a subsequent request references an existent EntityMap, it shall be used for the purposes of Entity registration matching, and queries shall be filtered to only consider the Entities listed. Subsequent requests referencing an EntityMap shall use the same parameters as in the original request that created the EntityMap, except for the specification of Entity identifiers or parameters related to pagination, or, in the case of temporal requests, the temporal query. If an EntityMap has expired, or cannot be accessed, no inference can be made as to which entities are held within the Context Sources and a new one shall be created. An EntityMap fixes the Entities to be considered for subsequent requests based on it. The creating Context Source shall remove Entities from the EntityMap that do not match the filters of the query at the time of processing. Other components shall only be allowed to update the expiry timestamp of the EntityMap, which can optionally be extended if the Context Sources implementation allows for it.

-

5.5.15 Snapshot Behaviour

-

If a Snapshot(see clause 4.3.7) is specified for an NGSI-LD operation, the operation shall only be applied to information related to the specific Snapshot. Operations permitted on Snapshots are the same as those specified for the Core API and, if supported, the Temporal API (see Table 4.3.5-1). This means all operations are implicitly limited to a local scope with all relaxations allowing broader operations (see clause 5.5.13) and there is no need to explicitly set the local scope as a request parameter.The implicit limitation to local scope also means that Context Source Registrations from the Context Registry will not be used.

-

Snapshots are explicitly created, and the Snapshotidentifier is provided on creation. How the Snapshotidentifier is specified for an API operation is protocol binding specific.

-

The Snapshotconcept is orthogonal to the Tenant concept (see clause 4.14). Snapshots can also be created on Tenants. To execute an operation on a Snapshot created on a Tenant, both Snapshot and Tenant (see clause 5.5.10) have to be specified for an API operation.

-

If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be deleted, the snapshotPriority, ranging from 1 (minimum) to 10 (maximum) with 5 being the default priority, should be considered. An implementation may also consider other aspects like the expiresAt, or lastUsedAt timestamp for such a decision.

-

5.6 Context Information Provision

-

5.6.1 Create Entity

-

5.6.1.1 Description

-

This operation allows creating a new NGSI-LD Entity.

-

5.6.1.2 Use case diagram

-

A Context Producer can create an Entity within an NGSI-LD system as shown in Figure 5.6.1.2‑1.

-
-

-
-
-

Figure 5.6.1.2-1: Create entity use case

-
-

5.6.1.3 Input data

-

A JSON-LD document representing an NGSI-LD Entity as mandated by clause 5.2.4.

-

5.6.1.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If an exclusive Context Source Registration already exists for this Entity id (URI), Attributes from matching input data are forwarded for remote processing:
    • -
-
-
    -
  • -

    For matching Registrations where the Create Entity operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this shall result in an error in case the complete create failed or in a partial success if some parts of the create succeeded.

    -
    • -
  • -

    For matching Registrations where the Create Entity operation is not supported, this shall result in an error of type Conflict if the complete Create Entity operation failed or in a partial success if some parts of it succeeded.

    -
    -
    -

    The matching Attributes are then removed from the Fragment and not processed further.

    -
    • -
-
-
    -
  • If any redirect Context Source Registrations exist that match against the input data, that input data is forwarded for remote processing by one or more matching endpoints:
    • -
-
-
-
    -
  • For matching Registrations where the Create Entity operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in an error in case the complete create has failed or in a partial success if some parts of the create has succeeded.
    • -
  • For matching redirect Registrations where the Create Entity operation is not supported, this shall result in an error of type Conflict if the complete Create Entity operation failed or in a partial success if some parts of it succeeded.
    • -
-
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded for remote processing by matching endpoints in case the Create Entity operation is supported.
    • -
  • If the Entity already exists locally this shall result in an error of type AlreadyExists, if the complete Create Entity operation has failed or in a partial success if some parts of it has succeeded.
    • -
  • Any remaining input data shall be used to create the Entity locally.
    • -
-
-

5.6.1.5 Output data

-

A URI identifying the newly created Entity.

-

5.6.2 Update Attributes

-

5.6.2.1 Description

-

This operation allows modifying an existing NGSI-LD Entity by updating already existing Attributes (Properties or Relationships) and by appending non-existing ones.

-

5.6.2.2 Use case diagram

-

A Context Producer can update Attributes within an NGSI-LD system as shown in Figure 5.6.2.2‑1.

-
-

-
-
-

Figure 5.6.2.2-1: Update Attributes use case

-
-

5.6.2.3 Input data

-
-
    -
  • A URI representing the id of the Entity to be updated (target Entity).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • A JSON-LD document representing an NGSI-LD Entity Fragment.
    • -
-
-

5.6.2.4 Behaviour

-
-
    -
  • If the Entity ID is not present or it is not a valid URI then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent to the target entity held locally, and no matching registrations apply (see clause 5.12), an error of type ResourceNotFound shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type OperationNotSupported shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, Attributes from matching input data are forwarded for remote processing. For each matching registration:
    • -
-
-
-
    -
  • If the Update Attributes operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Update Attributes operation is not supported by the registration, this shall result in an error of type Conflict if the complete update failed or in a partial success if some parts of the update succeeded.
    • -
-
-
-
    -
  • The matching Attributes are then removed from the Fragment and not processed further.
    • -
  • If there are remaining Attributes, for any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints in case the Update Attributes operation is supported by the matched registration.
    • -
  • Then, implementations shall perform a partial update patch operation over the remains of the target Entity as mandated by clause 5.5.8, using the following procedure.
    • -
  • For each Attribute (Property or Relationship) included by the Entity Fragment at root level:
    • -
-
-
-
    -
  • If the target Entity does not include a matching Attribute (considering term expansion rules as mandated by clause 5.5.7) then such Attribute shall be appended to the target Entity.
    • -
  • If the target Entity already includes a matching Attribute (considering term expansion rules as mandated by clause 5.5.7):
    • -
-
-
-
    -
  • If a datasetId is present in the Attribute included by the Entity Fragment:
    • -
-
-
-
    -
  • If an Attribute instance in the target Entity has the samedatasetIddatasetIdcreatedAtclause 4.8
    • -
  • If an Attribute instance in the target Entity has the samedatasetIddatasetId
    • -
  • Otherwise the Attribute instance with the specifieddatasetId
    • -
-
-
-
    -
  • If no datasetId is present in the Attribute included by the Entity Fragment, the default Attribute instance is targeted:
    • -
-
-
-
    -
  • If the default Attribute instance is present and the Attribute value is not NGSI-LD Null,createdAtclause 4.8
    • -
  • If the default Attribute instance is present and the Attribute value is NGSI-LD Null,
    • -
  • Otherwise the default Attribute instance shall be appended to the target Entity.
    • -
-
-
-
    -
  • If type is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity.
    • -
  • If scope is included in the Fragment and the target entity includes scope, replace the scope by the one included in the Fragment, otherwise ignore it.
    • -
-
-

5.6.2.5 Output data

-
-
    -
  • A status code indicating whether all the new Attributes were updated or only some of them.
    • -
  • List of Attributes (Properties or Relationships) actually updated.
    • -
-
-

5.6.3 Append Attributes

-

5.6.3.1 Description

-

This operation allows modifying an NGSI-LD Entity by adding new attributes (Properties or Relationships).

-

5.6.3.2 Use case diagram

-

A Context Producer can append new Attributes to an existing Entity within an NGSI-LD system as shown in Figure 5.6.3.2‑1.

-
-

-
-
-

Figure 5.6.3.2-1: Append Attributes use case

-
-

5.6.3.3 Input data

-
-
    -
  • A URI representing the id of the E to be modified (target Entity).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • A JSON-LD document representing an NGSI-LD Entity Fragment.
    • -
  • An optional flag indicating whether overwriting existing Attributes within the append operation should be permitted or denied. By default, Attribute overwrites are permitted.
    • -
-
-

5.6.3.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
-
    -
  • If the Entity ID is not present or it is not a valid URI then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about this Entity, because there is no existing Entity which id (URI), and where specified type, is equivalent held locally to the one passed as a parameter, and no matching registrations apply (see clause 5.12), an error of type ResourceNotFound shall be raised.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration:
    • -
-
-
-
    -
  • If the Append Attributes operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Append Attributes operation is not supported by the registration, this shall result in an error of type Conflict if the complete append failed or in a partial success if some parts of the append succeeded.
    • -
-
-
-
    -
  • The matching Attributes are then removed from the Fragment and not processed further.
    • -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints in case the Append Attributes operation is supported.
    • -
  • Then, implementations shall perform an Append Attributes operation over the remains of the target Entity as using the following procedure:
    • -
-
-
-
    -
  • For each Attribute (Property or Relationship) included by the Entity Fragment at root level:
    • -
-
-
-
    -
  • If a datasetId is present in the Attribute included by the Entity Fragment:
    • -
-
-
-
    -
  • If no Attribute instance of the same target Entity exists that has the samedatasetId
    • -
  • If an Attribute instance of the same target Entity exists that has the samedatasetId:
    • -
  • If overwrite is allowed, then the existing Attribute with the specifieddatasetIdcreatedAtclause 4.8
    • -
  • If overwrite is not allowed, the existing Attribute with the specifieddatasetId
    • -
-
-
-
    -
  • If no datasetId is present in the Attribute included by the Entity Fragment:
    • -
-
-
-
    -
  • If no default Attribute instance of the same target Entity exists, then such Attribute shall be appended to the target Entity.
    • -
  • If a default Attribute instance of the same target Entity exists:
    • -
  • If overwrite is allowed, then the existing default Attribute in the target Entity shall be replaced by the new one supplied. The system generatedcreatedAtclause 4.8
    • -
  • If overwrite is not allowed the existing default Attribute in the target Entity shall be left untouched.
    • -
-
-
-
    -
  • If type is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity.
    • -
  • If scope is included in the Fragment and overwrite is allowed, the scope of the target Entity will become the one included in the Fragment. Otherwise, the Scopes in the Fragment that are not part of the value of scope of the target Entity will be appended to the value of the scope of the target Entity. If there is more than one Scope, the value of scope is represented as a JSON array containing all Scopes.
    • -
-
-

5.6.3.5 Output data

-
-
    -
  • A status code indicating whether all the new Attributes were appended or only some of them.
    • -
  • List of Attributes (Properties and/or Relationships) actually appended.
    • -
-
-

5.6.4 Partial Attribute update

-

5.6.4.1 Description

-

This operation allows performing a partial update on an NGSI-LD Entity’s Attribute (Property or Relationship). A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. This operation supports the deletion of sub-Attributes but not the deletion of the whole Attribute itself.

-

5.6.4.2 Use case diagram

-

A Context Producer can carry out a partial Attribute update of an Entity within an NGSI-LD System as shown in Figure 5.6.4.2‑1.

-
-

-
-
-

Figure 5.6.4.2-1: Partial Attribute update use case

-
-

5.6.4.3 Input data

-
-
    -
  • Entity ID (URI) of the concerned Entity, the target Entity.
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • Target Attribute (Property or Relationship) to be modified, identified by a name.
    • -
  • A JSON-LD document representing an NGSI-LD Attribute Fragment.
    • -
-
-

5.6.4.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not valid or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute is scope, then an error of type BadRequestData shall be raised.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type OperationNotSupported shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see clause 5.12), then an error of type ResourceNotFoundshall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration:
    • -
-
-
    -
  • -

    If the Partial Attribute update operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.

    -
    • -
  • -

    If the Partial Attribute update operation is not supported by the registration, this shall result in an error of type Conflict in case the complete partial Attribute update failed, or in a partial success if some parts of the partial Attribute update succeeded.

    -
    -
    -

    No further processing is required.

    -
    • -
-
-
    -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints in case the Partial Attribute update operation is supported.
    • -
  • Apply term expansion as mandated by clause 5.5.7, so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
  • If the target Entity does not contain the target Attribute:
    • -
-
-
-
    -
  • as a default instance in case no datasetId is present;
    • -
  • as an instance with the specified datasetId if present;
    • -
-
-
-

then an error of type ResourceNotFound shall be raised.

-
-
-
    -
  • Perform a partial update patch operation on the target Attribute following the algorithm mandated by clause 5.5.8. If present in the provided NGSI-LD Entity Fragment, the type of the Attribute has to be the same as the type of the targeted Attribute fragment, i.e. it is not allowed to change the type of an Attribute.
    • -
-
-

5.6.4.5 Output data

-

None.

-

5.6.5 Delete Attribute

-

5.6.5.1 Description

-

This operation allows deleting an NGSI-LD Attribute (Property or Relationship). The Attribute itself and all its children shall be deleted.

-

5.6.5.2 Use case diagram

-

A Context Producer can delete a specific Attribute within an NGSI-LD system as shown in Figure 5.6.5.2‑1.

-
-

-
-
-

Figure 5.6.5.2-1: Delete Attribute use case

-
-

5.6.5.3 Input data

-
-
    -
  • Entity ID (URI) of the concerned Entity, the target Entity.
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • Target Attribute (Property or Relationship) to be deleted, identified by a name.
    • -
  • An optional parameter identifying the datasetId of the target Attribute instance to be deleted. Otherwise the default Attribute instance is targeted.
    • -
  • An optional flag deleteAll indicating whether also all target Attribute instances with a datasetId are to be deleted.
    • -
  • An optional JSON-LD @context.
    • -
-
-

5.6.5.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not a valid name or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data (see clause 5.12), the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the Delete Attribute operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Delete Attribute update operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete delete Attribute failed, or in a partial success if some parts of the delete Attribute succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints in case the Delete Attribute operation is supported by the matched registration.
    • -
  • Apply term expansion as mandated by clause 5.5.7 so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
  • If the target Entity does not contain the target Attribute then an error of type ResourceNotFound shall be raised.
    • -
  • If the target Attribute is scope, remove the scope Attribute from the target Entity.
    • -
  • If the deleteAll flag is set, remove all target Attribute instances from the target Entity.
    • -
  • Otherwise:
    • -
-
-
-
    -
  • if a datasetId parameter is provided, remove only the target Attribute instance from the given dataset whose datasetId matches the parameter;
    • -
  • if no datasetId parameter is provided, remove the default target Attribute instance from the target Entity.
    • -
-
-

5.6.5.5 Output data

-

None.

-

5.6.6 Delete Entity

-

5.6.6.1 Description

-

This operation allows deleting an NGSI-LD Entity.

-

5.6.6.2 Use case diagram

-

A Context Producer can completely delete an Entity within an NGSI-LD system as shown in Figure 5.6.6.2‑1.

-
-

-
-
-

Figure 5.6.6.2-1: Delete Entity use case

-
-

5.6.6.3 Input data

-
-
    -
  • Entity ID (URI) of the Entity to be deleted, the target Entity.
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
-
-

5.6.6.4 Behaviour

-
-
    -
  • If the target Entity ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see clause 5.12), then an error of type ResourceNotFoundshall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the id, the request is forwarded for remote processing. For each matching registration:
    • -
-
-
-
    -
  • If the Delete Entity operation is supported by the registration (see clause 4.3.6), the request is forwarded to the Registration endpoint.
    • -
  • If the Delete Entity update operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete delete Entity failed, or in a partial success if some parts of the delete Entity succeeded.
    • -
-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded in the case the Delete Entity operation is supported for remote processing by matching endpoints.
    • -
  • The input data shall be used to remove the entity locally if it exists.
    • -
-
-

5.6.6.5 Output data

-

None.

-

5.6.7 Batch Entity Creation

-

5.6.7.1 Description

-

This operation allows creating a batch of NGSI-LD Entities.

-

5.6.7.2 Use case diagram

-

A Context Producer can create a batch of NGSI-LD Entities within an NGSI-LD system as shown in Figure 5.6.7.2‑1.

-
-

-
-
-

Figure 5.6.7.2-1: Create a batch of Entities use case

-
-

5.6.7.3 Input data

-
-
    -
  • A JSON-LD Array containing one or more JSON-LD documents each one representing an NGSI-LD Entity as mandated by clause 5.2.4. See clause 5.5.11.1 for information on behaviour when there is more than one instance of the same entity in the input Array.
    • -
-
-

5.6.7.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • If the input Array is empty or contains a null value in any of its items an error of type BadRequestData shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity successfully created. S shall be initialized to the empty array.
    • -
  • Let E be an array which shall contain a list of BatchEntityError as defined by clause 5.2.17, one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array.
    • -
  • For each Context Source Registration CSR in the Context Registry:
    • -
-
-
-
    -
  • Let IN be a copy of the original input array.
    • -
  • Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching exclusive Context Source Registration, which is not CSR itself.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching redirect Context Source Registration, unless CSR is a redirect Context Source Registration itself.
    • -
  • If IN is empty, continue with the next Context Source Registration if there is any.
    • -
  • If the Batch Entity Creation operation is supported by CSR:
    • -
-
-
-
    -
  • Forward the Batch Entity Creation request with IN as input Array.
    • -
  • Merge the returned list of Entities successfully created with S.
    • -
  • Merge the returned list of Entities in Error with E.
    • -
-
-
-
    -
  • Otherwise, if the Create Entity operation (clause 5.6.1) is supported by CSR:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward a Create Entity request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN created with S.
    • -
  • Merge any error result(s) for Entity EN created with E.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • In case CSR is an exclusive or redirect Context Source Registration, add an Error of type Conflict for each Entity in IN to E.
    • -
-
-
-
    -
  • For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by clause 5.6.1, but limited to a local operation, as follows:
    • -
-
-
-
    -
  • If the Entity was successfully created, then add the corresponding Entity ID to the S array.
    • -
  • If the Entity creation failed, then a new BatchEntityError shall be added to E containing the failed Entity ID and the related ProblemDetails.
    • -
-
-

5.6.7.5 Output data

-
-
    -
  • The list of Entities successfully created (S Array), if all Entities were created correctly; or
    • -
  • the list of Entities successfully created (S Array) and the list of Entities in error (E Array), if only some or none of the Entities were created.
    • -
-
-

5.6.8 Batch Entity Creation or Update (Upsert)

-

5.6.8.1 Description

-

This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed. In some database jargon this kind of operation is known as “upsert”.

-

5.6.8.2 Use case diagram

-

A Context Producer can create or update a batch of Entities within an NGSI-LD system as shown in Figure 5.6.8.2‑1.

-
-

-
-
-

Figure 5.6.8.2-1: Upsert a batch of Entities use case

-
-

5.6.8.3 Input data

-
-
    -
  • A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by clause 5.2.4. See clause 5.5.11.2 for information on behaviour when there is more than one instance of the same entity in the input Array.
    • -
  • An optional flag indicating the update mode (only applies in case the Entity already exists):
    • -
-
-
-
    -
  • Replace. All the existing Entity content shall be replaced (default mode).
    • -
  • Update. Existing Entity content shall be updated.
    • -
-
-

5.6.8.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • If the input Array is empty or contains a null value in any of its items, an error of type BadRequestData shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized to the empty array.
    • -
  • Let E be an array which shall contain a list of BatchEntityError as defined by clause 5.2.17, one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array.
    • -
  • For each Context Source Registration CSR in the Context Registry:
    • -
-
-
-
    -
  • Let IN be a copy of the original input array.
    • -
  • Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching exclusive Context Source Registration, which is not CSR itself.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching redirect Context Source Registration, unless CSR is a redirect Context Source Registration itself.
    • -
  • If IN is empty, continue with the next Context Source Registration if there is any.
    • -
  • If the Batch Entity Creation or Update (Upsert) operation is supported by CSR:
    • -
-
-
-
    -
  • Forward the Batch Entity Creation or Update (Upsert) request with IN as input Array.
    • -
  • Merge the returned list of Entities successfully created with S.
    • -
  • Merge the returned list of Entities in Error with E.
    • -
-
-
-
    -
  • Otherwise, if the Create Entity operation (clause 5.6.1) is supported by CSR:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward a Create Entity request for Entity EN.
    • -
  • If an error of typeAlreadyExists
    • -
  • If the Replace Entity operation(clause 5.6.18Replace
    • -
  • Otherwise, if the Update Attributes operation(clause 5.6.2Update
    • -
  • Otherwise add anOperationNotSupported
    • -
-
-
-
    -
  • Merge any successful result(s) for Entity EN created or updated with S.
    • -
  • Merge any error result(s) for Entity EN created or updated with E.
    • -
-
-
-
    -
  • Otherwise, if the Replace Entity operation (clause 5.6.18) is supported by CSR and the value of the update mode flag is Replace or the flag is not set:
    • -
-
-
-
    -
  • Forward a Replace Entity request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN updated with S.
    • -
  • Merge any error result(s) for Entity EN updated with E.
    • -
-
-
-
    -
  • Otherwise, if the Update Attributes operation (clause 5.6.2) is supported by CSR and the value of the update mode flag is Update:
    • -
-
-
-
    -
  • Forward an Update Attributes request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN updated with S.
    • -
  • Merge any error result(s) for Entity EN updated with E.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • In case CSR is an exclusive or redirect Context Source Registration, add an Error of type Conflict for each Entity in IN to E.
    • -
-
-
-
    -
  • For each of the NGSI-LD Entities included in the input Array implementations shall:
    • -
-
-
-
    -
  • Create the Entity locally if it does not exist (i.e. no Entity with the same Entity ID is present) executing the behaviour defined by clause 5.6.1, but limited to a local operation.
    • -
  • If there were an existing Entity with the same Entity ID, it shall be completely replaced by the new Entity content provided, if the requested update mode is ‘replace’.
    • -
  • If there were an existing Entity with the same Entity ID, the behaviour defined by clause 5.6.2 shall be executed, but limited to a local operation, if the requested update mode is “update”.
    • -
-
-
-
    -
  • If successful, the local creation or update shall be added to S. If while processing an Entity there is any kind of error or abnormal situation, a BatchEntityError shall be added to E containing the failed Entity ID and the related ProblemDetails.
    • -
-
-

5.6.8.5 Output data

-
-
    -
  • none (if all Entities already existed and are successfully updated); or
    • -
  • the list of Entities successfully created (S Array), if all Entities not existing prior to this request have been successfully created and the others have been successfully updated; or
    • -
  • the list of Entities successfully created or updated (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully created or updated.
    • -
-
-

5.6.9 Batch Entity Update

-

5.6.9.1 Description

-

This operation allows updating a batch of NGSI-LD Entities.

-

5.6.9.2 Use case diagram

-

A Context Producer can update a batch of Entities within an NGSI-LD system as shown in Figure 5.6.9.2‑1.

-
-

-
-
-

Figure 5.6.9.2-1: Update a batch of Entities use case

-
-

5.6.9.3 Input data

-
-
    -
  • A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by clause 5.2.4. See clause 5.5.11.3 for information on behaviour when there is more than one instance of the same entity in the input Array.
    • -
  • An optional flag indicating whether Attributes shall be overwritten or not. By default, Attributes will be overwritten.
    • -
-
-

5.6.9.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • If the input Array is empty or contains a null value in any of its items, an error of type BadRequestData shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized as the empty array.
    • -
  • Let E be an array which shall contain a list of BatchEntityError as defined by clause 5.2.17, one for each NGSI-LD Entity which resulted in error. E shall be initialized as the empty array.
    • -
  • For each Context Source Registration CSR in the Context Registry:
    • -
-
-
-
    -
  • Let IN be a copy of the original input array.
    • -
  • Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching exclusive Context Source Registration, which is not CSR itself.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching redirect Context Source Registration, unless CSR is a redirect Context Source Registration itself.
    • -
  • Remove all Entities without Attributes from IN.
    • -
  • If IN is empty, continue with the next Context Source Registration if there is any.
    • -
  • If the Batch Entity Update operation is supported by CSR:
    • -
-
-
-
    -
  • Forward the Batch Entity Update request with IN as input Array.
    • -
  • Merge the returned list of Entities successfully created with S.
    • -
  • Merge the returned list of Entities in Error with E.
    • -
-
-
-
    -
  • Otherwise, if the Update Attributes operation (clause 5.6.2) is supported by CSR and Attribute overwrite is permitted:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward an Update Attributes request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN updated with S.
    • -
  • Merge any error result(s) for Entity EN updated with E.
    • -
-
-
-
    -
  • Otherwise, if the Append Attributes operation (clause 5.6.3) is supported by CSR and Attribute overwrite is not permitted:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward an Append Attributes request for Entity EN with Attribute overwrite disabled:
    • -
  • Merge any successful result(s) for Entity EN updated with S.
    • -
  • Merge any error result(s) for Entity EN updated with E.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • In case CSR is an exclusive or redirect Context Source Registration, add an Error of type Conflict for each Entity in IN to E.
    • -
-
-
-
    -
  • For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by clause 5.6.3, but limited to a local operation, as follows:
    • -
-
-
-
    -
  • If the Entity was successfully updated (Attributes appended), then add the corresponding Entity ID to the S array.
    • -
  • If the Entity update failed, then a new BatchEntityError shall be added to E containing the failed Entity ID and the ProblemDetails associated.
    • -
-
-

5.6.9.5 Output data

-
-
    -
  • none (if all Entities are successfully updated); or
    • -
  • the list of Entities successfully updated (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully updated.
    • -
-
-

5.6.10 Batch Entity Delete

-

5.6.10.1 Description

-

This operation allows deleting a batch of NGSI-LD Entities.

-

5.6.10.2 Use case diagram

-

A Context Producer can delete a batch of Entities within an NGSI-LD system as shown in Figure 5.6.10.2‑1.

-
-

-
-
-

Figure 5.6.10.2-1: Delete a batch of Entities use case

-
-

5.6.10.3 Input data

-
-
    -
  • A JSON-LD Array containing a list of Entity IDs (URIs) that are requested to be deleted. See clause 5.5.11.4 for information on behaviour when there is more than one instance of the same Entity ID in the input Array.
    • -
-
-

5.6.10.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • If the input Array is empty or contains a null value in any of its items, an error of type BadRequestData shall be raised.
    • -
  • Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized to the empty array.
    • -
  • Let E be an array which shall contain a list of BatchEntityError as defined by clause 5.2.17, one for each NGSI-LD Entity which resulted in error. E shall be initialized to the empty array.
    • -
  • For each Context Source Registration CSR in the Context Registry:
    • -
-
-
-
    -
  • Let IN be a copy of the original input array.
    • -
  • Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching exclusive Context Source Registration, which is not CSR itself.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching redirect Context Source Registration, unless CSR is a redirect Context Source Registration itself.
    • -
  • Remove all Entities without Attributes from IN.
    • -
  • If IN is empty, continue with the next Context Source Registration if there is any.
    • -
  • If the Batch Entity Delete operation is supported by CSR:
    • -
-
-
-
    -
  • Forward the Batch Entity Delete request with IN as input Array.
    • -
  • Merge the returned list of Entities successfully created with S.
    • -
  • Merge the returned list of Entities in Error with E.
    • -
-
-
-
    -
  • Otherwise, if the Delete Entity operation (clause 5.6.6) is supported by CSR:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward a Delete Entity request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN deleted with S.
    • -
  • Merge any error result(s) for Entity EN deleted with E.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • In case CSR is an exclusive or redirect Context Source Registration, add an Error of type Conflict for each Entity in IN to E.
    • -
  • For each of the NGSI-LD Entity IDs included in the input Array execute the behaviour defined by clause 5.6.6, but limited to a local operation, as follows:
    • -
-
-
-
    -
  • If the Entity corresponding to an Entity ID was successfully deleted, then add such Entity ID to the S array.
    • -
  • If the Entity deletion failed, then a newBatchEntityErrorProblemDetails
    • -
-
-

5.6.10.5 Output data

-
-
    -
  • none (if all Entities that already existed are successfully deleted); or
    • -
  • the list of Entities successfully deleted (S Array), and the list of Entities in error (E Array), if some or all of the Entities have not been successfully deleted.
    • -
-
-

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

-

5.6.11.1 Description

-

This operation allows creating or updating (by adding new Attribute instances) the Temporal Evolution of an Entity.

-

5.6.11.2 Use case diagram

-

A Context Producer can create the Temporal Evolution of an Entity within an NGSI-LD system as shown in Figure 5.6.11.2‑1.

-

Similarly, if the Entity already exists then an Update scenario will be in place.

-
-

-
-
-

Figure 5.6.11.2-1: Create or Update (Upsert) Temporal Evolution of an Entity use case

-
-

5.6.11.3 Input data

-

A JSON-LD document representing the Temporal Evolution of an Entity as mandated by clause 5.2.20.

-

5.6.11.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If an exclusive Context Source Registration already exists for this Entity id (URI), Attributes from matching input data are forwarded for remote processing:
    • -
-
-
    -
  • -

    For matching Registrations where the “Create or Update (Upsert) Temporal Evolution of an Entity” operation is supported, the operation is forwarded to the registration endpoint. If the endpoint then raises an error, this shall result in an error in case the complete “Create or Update (Upsert) Temporal Evolution of an Entity” operation failed or in a partial success if some parts of it succeeded.

    -
    • -
  • -

    For matching Registrations where the “Create Entity” operation is not supported, this shall result in an error of type Conflict in case the complete “Create or Update (Upsert) Temporal Evolution of an Entity” operation failed or in a partial success if some parts of it succeeded.

    -
    -
    -

    The matching Attributes are then removed from the Fragment and not processed further.

    -
    • -
-
-
    -
  • If any redirect Context Source Registrations exist that match against the input data, that input data is forwarded for remote processing by one or more matching endpoints:
    • -
-
-
-
    -
  • For matching Registrations where the “Create or Update (Upsert) Temporal Evolution of an Entity” operation is supported, matching input data is forwarded. If any such endpoint then raises an error, this shall result in an error in case the complete “Create or Update (Upsert) Temporal Evolution of an Entity” operation failed or in a partial success if some parts of it succeeded.
    • -
  • For matching redirect Registrations where the “Create or Update (Upsert) Temporal Evolution of an Entity” operation is not supported, this shall result in an error of type Conflict in case the complete “Create or Update (Upsert) Temporal Evolution of an Entity” operation failed or in a partial success if some parts of it succeeded.
    • -
-
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded for remote processing by matching endpoints.
    • -
  • If the NGSI-LD endpoint already knows about this Temporal Evolution of an Entity, because there is an existing Temporal Evolution of an Entity whose id (URI) is the same, then all the Attribute instances included by the Temporal Evolution shall be added to the existing Entity as mandated by clause 5.6.12. If type is included in the EntityTemporal Fragment and it includes Entity Type names that are not yet in the target Temporal Evolution of an Entity, add them to the list of Entity Type names of the target Temporal Evolution of anEntity.
    • -
  • Otherwise, implementations shall create the provided Temporal Evolution of an Entity.
    • -
-
-

5.6.11.5 Output data

-

On creation, a URI identifying the newly created Temporal Evolution of an Entity. None otherwise.

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.12.1 Description

-

This operation allows modifying the Temporal Evolution of an Entity by adding new Attribute instances.

-

5.6.12.2 Use case diagram

-

A Context Producer can add new Attributes or Attribute instances to an existing Temporal Evolution of an Entity within an NGSI-LD system as shown in Figure 5.6.12.2‑1.

-
-

-
-
-

Figure 5.6.12.2-1: Add Attributes to Temporal Evolution of an Entity use case

-
-

5.6.12.3 Input data

-
-
    -
  • Entity ID (URI) of the target Temporal Evolution of an Entity to be modified with additional Attributes.
    • -
  • A JSON-LD document representing an NGSI-LD Fragment of EntityTemporal, including only the new Attribute instance(s), and contained by an Array.
    • -
-
-

5.6.12.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
-
    -
  • If the Entity ID is not present or it is not a valid URI then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Temporal Evolution of an Entity, because there is no existing Temporal Evolution of an Entity whose id (URI) is equivalent to the one passed as a parameter held locally and no matching registrations apply, an error of type ResourceNotFound shall be raised.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the Attributes from matching input data are forwarded for remote processing. For each matching registration:
    • -
-
-
-
    -
  • If the “Add Attributes to Temporal Evolution of an Entity” operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint.
    • -
  • If the “Add Attributes to Temporal Evolution of an Entity” operation is not supported by the matched registration, this shall result in an error of type Conflict if the complete “Add Attributes to Temporal Evolution of an Entity”operation failed or in a partial success if some parts of it succeeded.
    • -
-
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded for remote processing to matching endpoints.
    • -
  • If the target Temporal Evolution of an Entity exists locally and matches against the remaining input data, implementations shall do the following:
    • -
-
-
-
    -
  • For each Attribute (Property or Relationship) instance included by the EntityTemporal Fragment at root level:
    • -
-
-
-
    -
  • The Attribute (considering term expansion rules as mandated by clause 5.5.7) instance(s) shall be added to the target Temporal Evolution of an Entity.
    • -
-
-
-
    -
  • If type is included in the EntityTemporal Fragment and it includes Entity Type names that are not yet in the target Temporal Evolution of an Entity, add them to the list of Entity Type names of the target Temporal Evolution of theEntity.
    • -
-
-

5.6.12.5 Output data

-

None.

-

5.6.13 Delete Attribute from Temporal Evolution of an Entity

-

5.6.13.1 Description

-

This operation allows deleting an Attribute (Property or Relationship) of the Temporal Evolution of an Entity. The Attribute itself and all its child NGSI-LD elements shall be deleted.

-

5.6.13.2 Use case diagram

-

A Context Producer can delete a specific Attribute of the Temporal Evolution of an Entity within an NGSI-LD system as shown in Figure 5.6.13.2‑1.

-
-

-
-
-

Figure 5.6.13.2-1: Delete Attribute from Temporal Evolution of an Entity use case

-
-

5.6.13.3 Input data

-
-
    -
  • Entity ID (URI) of the target Temporal Evolution of an Entity to be modified by removing the target Attribute.
    • -
  • Target Attribute (Property or Relationship) to be deleted, identified by a name.
    • -
  • An optional parameter identifying the dataset (datasetId) of the target Attribute instance to be deleted.
    • -
  • An optional parameter, a flag, (deleteAll) indicating whether all target Attribute instances are to be deleted, regardless of datasetId.
    • -
  • An optional JSON-LD @context.
    • -
-
-

5.6.13.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not a valid name, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Temporal Evolution of an Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the “Delete Attribute from Temporal Evolution of an Entity” operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint.
    • -
  • If the “Delete Attribute from Temporal Evolution of an Entity” operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete “Delete Attribute from Temporal Evolution of an Entity” failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints.
    • -
  • If the target Temporal Evolution of an Entity exists locally, implementations shall do the following:
    • -
-
-
-
    -
  • Apply term expansion as mandated by clause 5.5.7 so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
  • If the target Temporal Evolution of an Entity does not contain the target Attribute then an error of type ResourceNotFound shall be raised.
    • -
  • If the deleteAll flag is set, remove all target Attribute instances from the target Entity.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • if a datasetId parameter is provided, remove only any target Attribute instance from the given dataset;
    • -
  • if no datasetId parameter is provided, remove only the default target Attribute instance datasetId from the target Entity.
    • -
-
-

5.6.13.5 Output data

-

None.

-

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity

-

5.6.14.1 Description

-

This operation allows modifying a specific Attribute (Property or Relationship) instance, identified by its instanceId, of the Temporal Evolution of an Entity.

-

This operation enables the correction of wrong information that could have been previously added to the Temporal Evolution of an Entity.

-

5.6.14.2 Use case diagram

-

A Context Producer can modify a specific Attribute instance, identified by a given instanceId, of the Temporal Evolution of an Entitywithin an NGSI-LD system as shown in Figure 5.6.14.2‑1.

-
-

-
-
-

Figure 5.6.14.2-1: Modify Attribute Instance in Temporal Evolution of an Entity use case

-
-

5.6.14.3 Input data

-
-
    -
  • Entity ID (URI) of the target Temporal Evolution of an Entity to be modified by changing an instance of the target Attribute.
    • -
  • Target Attribute (Property or Relationship) to be modified, identified by a name.
    • -
  • Attribute instance to be modified, identified by its instanceId.
    • -
  • A JSON-LD document representing an NGSI-LD Fragment of EntityTemporal, including only the new Attribute instance, contained by an Array of exactly one item.
    • -
  • An optional JSON-LD @context.
    • -
-
-

5.6.14.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not a valid name or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target instanceId is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the “Modify Attribute instance in Temporal Evolution of an Entity” operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint.
    • -
  • If the “Modify Attribute instance in Temporal Evolution of an Entity” operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete Modify Attribute instance in Temporal Evolution of an Entity operation failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints.
    • -
  • If the target Temporal Evolution of an Entity exists locally, implementations shall do the following:
    • -
-
-
-
    -
  • Apply term expansion as mandated by clause 5.5.7 so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
  • If the target Temporal Evolution of an Entity does not contain the target Attribute then an error of type ResourceNotFound shall be raised.
    • -
  • If for the target Attribute no instance with the specified instanceId exists, an error of type ResourceNotFound shall be raised.
    • -
-
-
-
    -
  • Replace the target Attribute instance identified by the instanceId with the Attribute instance in the EntityTemporal Fragment. The createdAt property of the concerned instance shall remain unchanged, but the modifiedAt property shall be set to the timestamp corresponding to this modification.
    • -
-
-

5.6.14.5 Output data

-

None.

-

5.6.15 Delete Attribute instance from Temporal Evolution of an Entity

-

5.6.15.1 Description

-

This operation allows deleting one Attribute instance (Property or Relationship), identified by its instanceId, of the Temporal Evolution of an Entity. The Attribute itself and all its child elements shall be deleted. This operation enables the removal of individual Attribute instances that could have been previously added to the Temporal Evolution of an Entity.

-

5.6.15.2 Use case diagram

-

A Context Producer can delete an Attribute instance, identified by a given instanceId, of the Temporal Evolution of an Entity within an NGSI-LD system as shown in Figure 5.6.15.2‑1.

-
-

-
-
-

Figure 5.6.15.2-1: Delete Attribute Instance from Temporal Evolution of an Entity use case

-
-

5.6.15.3 Input data

-
-
    -
  • Entity ID (URI) of the target Temporal Evolutionof an Entity to be modified by deleting an instance of the target Attribute.
    • -
  • Target Attribute (Property or Relationship) to be deleted, identified by a name.
    • -
  • Attribute instance to be deleted, identified by its instanceId.
    • -
  • An optional JSON-LD @context.
    • -
-
-

5.6.15.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not a valid name or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the target instanceId is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the “Delete Attribute instance from Temporal Evolution of an Entity” operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint.
    • -
  • If the “Delete Attribute instance from Temporal Evolution of an Entity” operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete “Delete Attribute instance from Temporal Evolution of an Entity” failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints.
    • -
  • If the target Temporal Evolution of an Entity exists locally, implementations shall do the following:
    • -
-
-
-
    -
  • Apply term expansion as mandated by clause 5.5.7 so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
-
-
-
    -
  • If the target Temporal Evolution of the Entity does not contain the target Attribute then an error of type ResourceNotFound shall be raised.
    • -
  • If for the target Attribute no instance with the specified instanceId exists, an error of type ResourceNotFound shall be raised.
    • -
  • Remove the instance, with the specified instanceId, of the target Attribute from the target Entity.
    • -
-
-

5.6.15.5 Output data

-

None.

-

5.6.16 Delete Temporal Evolution of an Entity

-

5.6.16.1 Description

-

This operation allows deleting the Temporal Evolution of an Entity.

-

5.6.16.2 Use case diagram

-

A Context Producer can completely delete the Temporal Evolution of an Entity within an NGSI-LD system as shown in Figure 5.6.16.2‑1.

-
-

-
-
-

Figure 5.6.16.2-1: Delete Temporal Evolution of an Entity use case

-
-

5.6.16.3 Input data

-
-
    -
  • Entity ID (URI) of the target Temporal Evolution of an Entity to be deleted.
    • -
-
-

5.6.16.4 Behaviour

-
-
    -
  • If the target Entity ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity because there is no existing Entity whose id (URI) is equivalent held locally and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the “Delete Temporal Evolution of Entity” operation is supported by the matched registration, matching input data is forwarded to the Registration endpoint.
    • -
  • If the “Delete Temporal Evolution of Entity” operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete “Delete Temporal Evolution of Entity” failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the input data, that input data is also forwarded for remote processing to matching endpoints.
    • -
  • If the target Temporal Evolution of an Entity exists locally, the entire Temporal Evolution of the Entity shall be removed.
    • -
-
-

5.6.16.5 Output data

-

None.

-

5.6.17 Merge Entity

-

5.6.17.1 Description

-

This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch processing rules defined in IETF RFC 7396 [16] by adding new Attributes (Properties or Relationships) or modifying or deleting existing Attributes associated with an existing Entity.

-

5.6.17.2 Use case diagram

-

A Context Producer can perform a merge on an Entity within an NGSI-LD system as shown in Figure 5.6.17.2‑1.

-
-

-
-
-

Figure 5.6.17.2-1: Merge Entity use case

-
-

5.6.17.3 Input data

-
-
    -
  • A URI representing the id of the Entity to be merged (target Entity).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • A JSON-LD document representing an NGSI-LD Entity Fragment.
    • -
  • An optional flag indicating whether the JSON-LD document contains a simplified representation of the entity.
    • -
  • An optional parameter indicating a common observedAt timestamp to use across merged Attributes.
    • -
  • An optional parameter representing a common IETF RFC 5646 [28] language tag to use across merged LanguageMap Attributes.
    • -
-
-

5.6.17.4 Behaviour

-

The following behaviour shall be exhibited by compliant implementations:

-
-
    -
  • If the Entity ID is not present or it is not a valid URI then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see clause 5.12), then an error of type ResourceNotFound shall be raised.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, Attributes from matching input data are forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the Merge Entity operation is supported by the matched registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Merge Entity operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete Merge Entity operation failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

The matching Attributes are then removed from the Fragment and not processed further.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded in the case the Merge Entity operation is supported for remote processing to matching endpoints.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by this operation. If NGSI-LD Nulls are found in the payload, but are not supported, an error of type OperationNotSupported shall be raised.
    • -
-
-
-

Then, implementations shall perform a merge operation over the target Entity as mandated by clause 5.5.12, using the following procedure:

-
-
-

For each Attribute (Property or Relationship) included by the Entity Fragment:

-
-
-
    -
  • If the target Entity does not include a matching Attribute (considering term expansion rules as mandated by clause 5.5.7), then such Attribute shall be appended to the target Entity.
    • -
  • If the target Entity already includes a matching Attribute (considering term expansion rules as mandated by clause 5.5.7):
    • -
-
-
-
    -
  • If the Attribute (Property or Relationship) to be merged is represented in a simplified representation, the type of any pre-existing Attribute in the target entity shall be preserved.
    • -
  • If a common language tag is defined and a LanguageProperty Attribute to be merged is represented as a string, the pre-existing languageMap JSON object shall be preserved. The string value shall only replace the value associated to the language tag key found within the languageMap.
    • -
  • If a common observedAt timestamp is defined and an existing Attribute to be merged previously contained an observedAt sub-Attribute, the observedAt sub-Attribute is also updated using the common timestamp, unless the Entity Fragment itself contains an explicit updated value for the observedAt sub-Attribute.
    • -
  • If a datasetId is present in the Attribute included by the Entity Fragment:
    • -
-
-
-
    -
  • If an Attribute instance in the target Entity has the samedatasetId
    • -
  • If overwrite is allowed and the Attribute value is not NGSI-LD Null, then the existing Attribute with the specifieddatasetId
    • -
  • If overwrite is allowed and the Attribute value is NGSI-LD Null, then the existing Attribute with the specifieddatasetId
    • -
  • If overwrite is not allowed, the existing Attribute with the specifieddatasetId
    • -
  • Otherwise the Attribute instance with the specifieddatasetId
    • -
-
-
-
    -
  • If no datasetId is present in the Attribute included by the Entity Fragment, the default Attribute instance is targeted:
    • -
-
-
-
    -
  • If the default Attribute instance is present:
    • -
  • If overwrite is allowed and the Attribute value is not NGSI-LD Null, then the existing Attribute in the target Entity shall be merged with the new one supplied.
    • -
  • If overwrite is allowed and the Attribute value is NGSI-LD Null, then the existing Attribute with the specifieddatasetId
    • -
  • If overwrite is not allowed, the existing Attribute in the target Entity shall be left untouched.
    • -
  • Otherwise if value is not NGSI-LD Null, the default Attribute instance shall be appended to the target Entity.
    • -
-
-
-
    -
  • If type is included in the Fragment and it includes Entity Type names that are not yet in the target Entity, add them to the list of Entity Type names of the target Entity.
    • -
  • If scope is included in the Fragment and overwrite is allowed, the scope of the target Entity will become the one included in the Fragment. Otherwise, the Scopes in the Fragment that are not part of the value of scope of the target Entity will be appended to the value of the scope of the target Entity. If there is more than one Scope, the value of scope is represented as a JSON array containing all Scopes.
    • -
-
-

5.6.17.5 Output data

-
-
    -
  • A status code indicating whether all the Attributes were merged successfully.
    • -
  • List of Attributes (Properties and/or Relationships) actually merged.
    • -
-
-

5.6.18 Replace Entity

-

5.6.18.1 Description

-

This operation allows the modification of an existing NGSI-LD Entity by replacing all of the Attributes (Properties or Relationships).

-

5.6.18.2 Use case diagram

-

A Context Producer can replace an entire Entity within an NGSI-LD system as shown in Figure 5.6.18.2‑1.

-
-

-
-
-

Figure 5.6.18.2-1: Replace Entity use case

-
-

5.6.18.3 Input data

-
-
    -
  • A URI representing the id of the Entity to be replaced (target Entity).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • A JSON-LD document representing an NGSI-LD Entity.
    • -
-
-

5.6.18.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI or it is not present, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see clause 5.12), then an error of type ResourceNotFound shall be raised.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation. NGSI-LD Nulls are not supported by this operation.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, Attributes from matching input data are forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the Replace Entity operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Replace Entity operation is not supported by the registration, this shall result in an error of type Conflict in case the complete Replace Entity operation failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-
    -
  • The matching Attributes are then removed from the Fragment and not processed further.
    • -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded in the case the Replace Entity operation is supported for remote processing to matching endpoints.
    • -
  • If the target Entity exists locally, completely replace the existing Entity with the same Entity ID with the new Entity content provided. The system generated createdAt Temporal Property of the Entity as defined in clause 4.8 remain unchanged.
    • -
-
-

5.6.18.5 Output data

-

None.

-

5.6.19 Replace Attribute

-

5.6.19.1 Description

-

This operation allows the replacement of a single Attribute (Property or Relationship) within an NGSI-LD Entity.

-

5.6.19.2 Use case diagram

-

A Context Producer can carry out a replacement of an Attribute within an Entity within an NGSI-LD System as shown in Figure 5.6.19.2‑1.

-
-

-
-
-

Figure 5.6.19.2-1: Replace Attribute use case

-
-

5.6.19.3 Input data

-
-
    -
  • Entity ID (URI) of the concerned Entity, the target Entity.
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • Target Attribute (Property or Relationship) to be replaced, identified by a name.
    • -
  • A JSON-LD document representing an NGSI-LD Attribute Fragment.
    • -
-
-

5.6.19.4 Behaviour

-
-
    -
  • If the target Entity ID is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute name is not valid, then an error of type BadRequestData shall be raised.
    • -
  • If the target Attribute is scope, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI), and where specified type, is equivalent held locally, and no matching registrations apply (see clause 5.12), then an error of type ResourceNotFound shall be raised.
    • -
  • The behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If an exclusive or redirect Context Source Registration matches against the input data, the input data is forwarded. For each matching registration:
    • -
-
-
-
    -
  • If the Replace Attribute operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Replace Attribute operation is not supported by the registration, this shall result in an error of type Conflict in case the complete Replace Attribute operation failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-

No further processing is required.

-
-
-
    -
  • For any inclusive Context Source Registrations that match against the remaining input data, that input data is also forwarded in the case the Replace Attribute operation is supported for remote processing to matching endpoints.
    • -
  • Apply term expansion as mandated by clause 5.5.7, so that the fully qualified name (URI) associated to the target Attribute is properly obtained.
    • -
  • If the target Entity does not contain the target Attribute:
    • -
-
-
-
    -
  • as a default instance in case no datasetId is present;
    • -
  • as an instance with the specified datasetId if present;
    • -
  • then this shall result in an error of type ResourceNotFound in case the complete Replace Attribute operation failed, or in a partial success if some parts of it succeeded.
    • -
-
-
-
    -
  • Completely replace the existing Attribute instance with the new Attribute content provided. The system generated createdAt Temporal Property as defined in clause 4.8 remains unchanged.
    • -
-
-

5.6.19.5 Output data

-

None.

-

5.6.20 Batch Entity Merge

-

5.6.20.1 Description

-

This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch processing rules defined in IETF RFC 7396 [16] by adding new attributes (Properties or Relationships) or modifying or deleting existing attributes associated with an existing Entity.

-

5.6.20.2 Use case diagram

-

A Context Producer can merge a batch of Entities within an NGSI-LD system as shown in Figure 5.6.20.2‑1.

-
-

-
-
-

Figure 5.6.20.2-1: Merge a batch of Entities use case

-
-

5.6.20.3 Input data

-

A JSON-LD Array containing one or more JSON-LD documents each one representing an Entity as mandated by clause 5.2.4. See clause 5.5.11.5 for information on behaviour when there is more than one instance of the same entity in the input Array.

-

5.6.20.4 Behaviour

-

Implementations shall exhibit the following behaviour:

-
-
    -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • Let S be an array which shall contain a list of Entity IDs, one for each NGSI-LD Entity which was successfully processed. S shall be initialized as the empty array.
    • -
  • Let E be an array which shall contain a list of BatchEntityError as defined by clause 5.2.17, one for each NGSI-LD Entity which resulted in error. E shall be initialized as the empty array.
    • -
  • For each Context Source Registration CSR in the Context Registry:
    • -
-
-
-
    -
  • Let IN be a copy of the original input array.
    • -
  • Remove from IN all Entities not matched by CSR and remove non-matching Attributes from the remaining Entities.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching exclusive Context Source Registration, which is not CSR itself.
    • -
  • Remove all Attributes from the remaining Entities in IN for which there is a matching redirect Context Source Registration, unless CSR is a redirect Context Source Registration itself.
    • -
  • Remove all Entities without Attributes from IN.
    • -
  • If IN is empty, continue with the next Context Source Registration if there is any.
    • -
  • If the Batch Entity Merge operation is supported by CSR:
    • -
-
-
-
    -
  • Forward the Batch Entity Merge request with IN as input Array.
    • -
  • Merge the returned list of Entities successfully created with S.
    • -
  • Merge the returned list of Entities in Error with E.
    • -
-
-
-
    -
  • Otherwise, if the Merge Entity operation (clause 5.6.17) is supported by CSR:
    • -
-
-
-
    -
  • For each Entity EN in the input array:
    • -
-
-
-
    -
  • Forward a Merge Entity request for Entity EN.
    • -
  • Merge any successful result(s) for Entity EN merged with S.
    • -
  • Merge any error result(s) for Entity EN merged with E.
    • -
-
-
-
    -
  • Otherwise:
    • -
-
-
-
    -
  • In case CSR is an exclusive or redirect Context Source Registration, add an Error of type Conflict for each Entity in IN to E.
    • -
-
-
-
    -
  • For each of the NGSI-LD Entities included in the input Array execute the behaviour defined by clause 5.6.17, but limited to a local operation, as follows:
    • -
-
-
-
    -
  • If the Entity was successfully merged (Attributes updated, appended or deleted), then add the corresponding Entity ID to the S array.
    • -
  • If the Entity merge failed, then a new BatchEntityError shall be added to E containing the failed Entity ID and the ProblemDetails associated.
    • -
-
-

5.6.20.5 Output data

-
-
    -
  • none (if all Entities already existed and are successfully merged); or
    • -
  • the list of Entities successfully merged (S Array), and the list of Entities in error (E Array), if only some or none of the Entities have been successfully merged.
    • -
-
-

5.6.21 Purge Entities

-

5.6.21.1 Description

-

This operation allows the deletion of entities within an NGSI-LD system based upon a query.

-

5.6.21.2 Use case diagram

-

A Context Producer can delete a set of entities which matches a specific query from an NGSI-LD system as shown in Figure 5.6.21.2‑1.

-
-

-
-
-

Figure 5.6.21.2-1: Purge Entities use case

-
-

5.6.21.3 Input data

-
-
    -
  • A reference to a JSON-LD @context (optional).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector.
    • -
  • A list (one or more) of Entity identifiers (optional).
    • -
  • A restrictive list of Attribute names to be deleted as attributes (optional).
    • -
  • An exclusionary list Attribute names to be kept as attributes (optional).
    • -
  • An id pattern as a regular expression (optional).
    • -
  • An NGSI-LD query (to filter out Entities by Attribute values) as per clause 4.9 (optional).
    • -
  • An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by clause 4.10 (optional).
    • -
  • A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by clause 4.19 (optional).
    • -
  • An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties that describe them) as per clause 4.9 (optional).
    • -
-
-

In the general case, it is not possible to purge a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.6.21.4 Behaviour

-
-
    -
  • At least one of the following input data shall be provided:
    • -
-
-
    -

  1. selector of Entity Types;

    2. -

  2. list of Attribute names, including at least one non-system Attribute;

    3. -

  3. NGSI-LD Query, including at least one non-system Attribute;

    4. -

  4. NGSI-LD GeoQuery;

    5. -

  5. local scope (see clause 5.5.13).

    6. -
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
-
    -
  • If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses 4.9 and 4.10) an error of type BadRequestData shall be raised.
    • -
  • If projection attributes are present and indicate the use of Linked Entityretrieval, then an error of type BadRequestData shall be raised.
    • -
  • If the filter conditions specified by the query includes Linked Entity attributes then an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of type and Attribute names shall be performed, as mandated by clause 5.5.7.
    • -
  • Otherwise, implementations shall run a Query Entities operation (clause 5.6.2) to retrieve a list of ids of Entities for deletion, that meet all of the following conditions (given the respective parameter is provided):
    • -
-
-
    -
  • -

    id is equal to any of the id(s) passed as a parameter;

    -
    • -
  • -

    the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter;

    -
    • -
  • -

    Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter;

    -
    • -
  • -

    id matches the id pattern passed as a parameter;

    -
    • -
  • -

    the filter conditions specified by the query are met (as mandated by clause 4.9);

    -
    • -
  • -

    the geospatial restrictions imposed by the geoquery are met (as mandated by clause 4.10); if there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions;

    -
    • -
  • -

    if the Scope query is present, it shall match a present Entity Scope (as mandated by clause 4.19, for an example see annex C, clause C.5.15).

    -
    -
    -

    And thereafter:

    -
    • -
  • -

    when no restrictive list of Entity member names is present, the implementation shall delete all Entities that can be found locally using retrieved list of Entity ids;

    -
    • -
  • -

    when a restrictive list of Entity member names is present, the implementation shall delete the given set of Attributes with those member names from all Entities that can be found locally using retrieved list of Entity ids;

    -
    • -
  • -

    when an exclusionary list of Entity member names is present, the implementation shall delete all but the given set of Attributes with those member names from all Entities that can be found locally using retrieved list of Entity ids.

    -
    • -
-
-
    -
  • Unless local scope is specified (see clause 5.5.13), for Context Source Registrations that match the query and support the “purgeEntity” operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
  • If an inclusive, exclusive or redirect Context Source Registration matches against the filter conditions specified, the request is forwarded for remote processing. For each matching registration:
    • -
-
-
-
    -
  • If the Purge Entity operation is supported by the registration (see clause 4.3.6), matching input data is forwarded to the Registration endpoint.
    • -
  • If the Purge Entity operation is not supported by the matched registration, this shall result in an error of type Conflict in case the complete purge Entities failed, or in a partial success if some parts of purge Entities succeeded.
    • -
-
-

5.6.21.5 Output data

-

None.

-

5.7 Context Information Consumption

-

5.7.1 Retrieve Entity

-

5.7.1.1 Description

-

This operation allows retrieving an NGSI-LD Entity.

-

5.7.1.2 Use case diagram

-

A Context Consumer can retrieve a specific Entity from an NGSI-LD system as shown in Figure 5.7.1.2‑1.

-
-

-
-
-

Figure 5.7.1.2-1: Retrieve Entity use case

-
-

5.7.1.3 Input data

-
-
    -
  • Entity ID (URI) of the Entity to be retrieved (target Entity).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional).
    • -
  • List of Attribute (Properties or Relationships) names to be retrieved (projection attributes) (optional).
    • -
  • A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).
    • -
  • An exclusionary list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).
    • -
  • A language filter as defined by clause 4.15 (optional).
    • -
  • An optional JSON-LD context.
    • -
  • In the case of a GeoJSON representation, the name of the GeoProperty attribute to use as the geometry for the GeoJSON representation as mandated by clause 4.5.16 (optional).
    • -
  • An optional flag indicating whether to include additional Linked Entities corresponding to the Relationships retrieved and how to format those Linked Entities. See clause 4.5.23 (optional).
    • -
  • A limit to the depth of Linked Entities to search whilst traversing an Entity graph. See clause 4.5.23 (optional).
    • -
  • A list (one or more) of Linked Entity identifiers previously encountered whilst traversing an Entity graph. See clause 4.5.23 (optional).
    • -
  • A flag indicating whether to return the location of the EntityMap used within the operation (optional).
    • -
  • A suggested lifetime for the EntityMap, if EntityMap is to be created (optional).
    • -
  • The location of a resource holding an EntityMap of matching Entity registrations (optional).
    • -
  • A datasetIdparameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).
    • -
-
-

5.7.1.4 Behaviour

-
-
    -
  • If the Entity ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If geometryProperty parameter is present and the Accept Header is not set to “application/geo+json”, then an error of type BadRequestData shall be raised.
    • -
  • If projection attributes are present and indicate the use of Linked Entityretrieval and the use of Linked Entityretrieval is not specified, or the projected attribute depth exceeds the Linked Entityretrieval depth, an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity held locally whose id (URI), and where specified type, is equivalent, and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • The implementation shall retrieve any Attribute data held locally which is associated with the Entity defined by the Entity ID.
    • -
  • If the ContextBroker implementation supports the use of EntityMaps then:
    • -
-
-
-
    -
  • If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved:
    • -
-
-
-
    -
  • If the resource cannot be found, or the data has expired, a new EntityMap shall be created.
    • -
  • If the data has not expired, only the retrieved Entity Map shall be used to determine which Context Source Registrations match the Entity ID.
    • -
-
-
-
    -
  • If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created.
    • -
-
-
-
    -
  • For Context Source Registrations that match and support the retrieveEntity operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
-
-
-
    -
  • If an EntityMap is in use for this operation, and an EntityMap entry linked to a Context Source Registration is found, the location of the linked EntityMap shall be passed as part of any forwarded request.
    • -
  • For any exclusive, redirect and inclusive Context Source Registrations, the request is forwarded for remote retrieval by matching endpoints, and remote Attribute data for the Entity is received. If an expiresAt DateTime is present on the Entity and the date lies in the past, the Attribute data shall be discarded, otherwise the Attribute data is then merged together according to the algorithm defined in clause 4.5.5.
    • -
  • For any auxiliary Context Source Registrations the remote Attribute data received is added to the payload only when an Attribute is not present in any of the Attribute data received elsewhere.
    • -
  • If an EntityMap is in use for this operation, the EntityMap’s linked maps are updated to hold the location of every EntityMap used by the Context Source Registrations.
    • -
-
-
-
    -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • For each Attribute found in the target Entity, when the datasetIdparameter is provided in the request:
    • -
-
-
-
    -
  • Filter the Attribute instances based on the datasetIdparameter, i.e. keep only the Attribute instances whose datasetId is specified. The default Attribute instance is matched, if “@none” is specified.
    • -
  • If there is no Attribute instance whose datasetIdmatches the value of the parameter, the Attribute shall not be returned with the Entity.
    • -
-
-
-
    -
  • If the optional Attribute list is present and the NGSI-LD endpoint does know about a matching Entity for the Entity ID, but this Entity does not have any of the Attributes in the Attribute list, then an error of type ResourceNotFound shall be raised.
    • -
  • If the Accept Header is set to “application/json” or “application/ld+json”, return a JSON-LD object representing the Entity as mandated by clause 5.2.4 and containing only the Attributes requested (if present).
    • -
-
-
-
    -
  • If the Prefer Header [26] is set to “ngsi-ld=<version>” then the ContextBroker shall endeavour to amend the JSON-LD object to conform to the specified version of the NGSI-LD specification as mandated in clause 4.3.6.8, and return a Preference-Applied Header set to “ngsi-ld=<conformant-version>” in the response.
    • -
-
-
-
    -
  • If the Accept Header is set to “application/geo+json”, a GeoJSON Feature object representing the entity as mandated by clause 5.2.29 and containing only the Attributes requested (if present):
    • -
-
-
-
    -
  • If the Prefer Header is omitted or set to “body=ld+json” then the Feature object will also contain an @context field.
    • -
  • If the Prefer Header is set to “body=json” the @context is set as a Link Header and removed from the Feature object.
    • -
-
-

5.7.1.5 Output data

-

A JSON-LD object representing the target Entity as mandated by clause 5.2.4 or a GeoJSON Feature as mandated by clause 5.2.29.

-

If a restrictive list of Entity member names is present, the Entity is reduced down to only contain the defined Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval).

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval).

-

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be compacted according to the supplied @context.

-

If a language filter is specified and any of the returned Attributes corresponds to a LanguageProperty, the LanguageProperty in question shall be converted into a Property. The value of this Property shall correspond to the value of the string or strings from the matching key-value pair of the languageMap where the key matches the language filter. A non-reified subproperty lang shall be included in the response indicating the chosen language.

-

If no match can be made for a LanguageProperty then a single language shall be chosen, up to the implementation.

-

If inline Linked Entity retrieval (see clause 4.5.23.2) is specified, and any of the returned Attributes corresponds to an annotated Relationship, then unless a URI has been previously encountered, an entity sub-Property shall be included in the response holding the Linked Entity data for each URI corresponding to that Relationship’s target object URI. If any of the returned Attributes corresponds to an annotated ListRelationship, then an entityList subproperty shall be included in the response holding the ordered array of Linked Entities corresponding to that ListRelationship’s target objectList URIs unless a URI has been previously encountered.

-

If flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, the response shall be an array of JSON-LD objects representing the target entity itself and the targets of its Relationships. If any of the returned Attributes corresponds to an annotated Relationship, unless a target URI has been previously encountered, thedata corresponding to each URI of the Relationship’s target object URIs is appended to the array. If any of the returned Attributes corresponds to an annotated ListRelationship, then an ordered array of additional Linked Entities is appended to the array which hold the data corresponding to each of the URIs found within ListRelationship’s target objectList unless a URI has been previously encountered.

-

Flattened Linked Entity retrieval output changes to a GeoJSON FeatureCollection as mandated by clause 5.2.30 if the Accept Header is set to “application/geo+json”.

-

If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response.

-

5.7.2 Query Entities

-

5.7.2.1 Description

-

This operation allows querying an NGSI-LD system.

-

5.7.2.2 Use case diagram

-

A Context Consumer can retrieve a set of entities which matches a specific query from an NGSI-LD system as shown in Figure 5.7.2.2‑1.

-
-

-
-
-

Figure 5.7.2.2-1: Query Entities use case

-
-

5.7.2.3 Input data

-
-
    -
  • A reference to a JSON-LD @context (optional).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector.
    • -
  • A list (one or more) of Entity identifiers (optional).
    • -
  • An id pattern as a regular expression (optional).
    • -
  • An NGSI-LD query (to filter out Entities by Attribute values) as per clause 4.9 (optional).
    • -
  • An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by clause 4.10 (optional).
    • -
  • A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by clause 4.19 (optional).
    • -
  • A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).
    • -
  • An exclusionary list member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).
    • -
  • A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional, deprecated).
    • -
  • An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties that describe them) as per clause 4.9 (optional).
    • -
  • A limit to the number of Entities to be retrieved. See clause 5.5.9.
    • -
  • A specified language filter as per clause 4.15 (optional).
    • -
  • A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional).
    • -
  • An optional flag indicating whether to include additional Linked Entities corresponding to the Relationships retrieved and how to format those Linked Entities. See clause 4.5.23 (optional).
    • -
  • A limit to the depth of Linked Entities to search whilst traversing an Entity Graph. See clause 4.5.23 (optional).
    • -
  • A list (one or more) of Linked Entity identifiers previously encountered whilst traversing an Entity Graph. See clause 4.5.23 (optional).
    • -
  • A flag indicating whether to return the location of the EntityMap used within the operation (optional).
    • -
  • A suggested lifetime for the EntityMap, if EntityMap is to be created (optional).
    • -
  • The location of a resource holding an EntityMap of matching Entity registrations (optional).
    • -
  • A datasetId parameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).
    • -
  • A list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be used to define the preferred ordering of Entities retrieved (Entity ordering attributes as defined by clause 4.23) (optional).
    • -
  • A preferred collation setting to be used when applying ordering of Entities (optional).
    • -
  • A location to be used when applying ordering of Entities (optional).
    • -
  • A defined geometry type to be used when applying ordering of Entities (optional).
    • -
  • A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional).
    • -
  • In the case of GeoJSON representation, the name of the GeoProperty attribute to use as the geometry for the GeoJSON representation as mandated by clause 4.5.16 (optional).
    • -
-
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.7.2.4 Behaviour

-
-
    -
  • At least one of the following input data shall be provided:
    • -
-
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
-
    -
  • If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses 4.9 and 4.10) an error of type BadRequestData shall be raised.
    • -
  • If projection attributes are present and indicate the use of Linked Entityretrieval, and the use of Linked Entityretrieval is not specified, or the projected attribute depth exceeds the Linked Entityretrieval depth, then an error of type BadRequestData shall be raised.
    • -
  • If the filter conditions specified by the query includes Linked Entity attributes, and the use of Linked Entityretrieval is not specified, or the Linked Entityattribute query depth exceeds the Linked Entityretrieval depth, an error of type BadRequestData shall be raised (too deep query).
    • -
  • If geometryProperty parameter is present and the Accept Header is not set to “application/geo+json”, then an error of type BadRequestData shall be raised.
    • -
  • If the ordering parameter is present and the execution of the operation is not limited to the local scope (see clause 5.5.13) then an error of type BadRequestData shall be raised.
    • -
  • If the ordering parameter is present and refers to ordering by distance and no location is present, then an error of type BadRequestData shall be raised.
    • -
  • If a preferred collation setting is present and it does not conform to a valid ICU collation (see IETF RFC 6067 [36]) then an error of type BadRequestData shall be raised.
    • -
  • If a location to be used when applying ordering of Entities setting is present and it is not syntactically valid (as per the referred clauses 4.9 and 4.10) or an error of type BadRequestData shall be raised.
    • -
  • Otherwise,
    • -
-
-
-
    -
  • Term to URI expansion of type and Attribute names shall be performed, as mandated by clause 5.5.7.
    • -
  • If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by clause 5.5.7.
    • -
-
-
-
    -
  • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided):
    • -
-
-
-
    -
  • id is equal to any of the id(s) passed as a parameter;
    • -
  • the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter;
    • -
  • id matches the id pattern passed as a parameter.
    • -
-
-
-
    -
  • otherwise, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided):
    • -
-
-
-
    -
  • id is equal to any of the id(s) passed as a parameter;
    • -
  • the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter;
    • -
  • Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter;
    • -
  • id matches the id pattern passed as a parameter;
    • -
  • the filter conditions specified by the query are met (as mandated by clause 4.9);
    • -
  • the geospatial restrictions imposed by the geoquery are met (as mandated by clause 4.10); if there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions;
    • -
  • if the Scope query is present, it shall match a present Entity Scope (as mandated by clause 4.19, for an example see annex C, clause C.5.15);
    • -
  • if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list.
    • -
-
-
-
    -
  • If the ContextBroker implementation supports the use of EntityMaps then:
    • -
-
-
-
    -
  • If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved:
    • -
-
-
-
    -
  • If the resource cannot be found, or the data has expired, a new EntityMap shall be created.
    • -
  • If the data has not expired, only the retrieved EntityMap shall be used to determine which Context Source Registrations match the Entity ID.
    • -
-
-
-
    -
  • If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created.
    • -
-
-
-
    -
  • Unless local scope is specified (see clause 5.5.13), for Context Source Registrations that match the query and support the “queryEntity” operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
-
-
-
    -
  • If an EntityMap is in use for this operation, and an EntityMap entry linked to a Context Source Registration is found, the location of the EntityMap shall be passed as part of the forwarded request.
    • -
  • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. These filters then have to be applied after the Entity information from different Context Sources and local information, if there is any, has been aggregated.
    • -
  • For any exclusive, redirect and inclusive Context Source Registrations, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an Entity Array. Within each Entity Array, any Entities where an expiresAt DateTime is present and the date lies in the past shall be discarded. The Entity Arrays are then merged together with the locally queried result according to the algorithm defined in clause 4.5.5.
    • -
  • For any auxiliary Context Source Registrations, the request is forwarded for remote querying by matching endpoints. Data from the Entity Array received is added to the payload only when an Attribute is not already present in the merged Entity Arrays are received elsewhere.
    • -
-
-
-
    -
  • If split Entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split Entities, and local scope is not specified, the following filters shall be applied on the aggregated Entities:
    • -
-
-
-
    -
  • the filter conditions specified by the query are met (as mandated by clause 4.9);
    • -
  • the geospatial restrictions imposed by the geoquery are met (as mandated by clause 4.10); if there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions;
    • -
  • if the Scope query is present, it shall match a present Entity Scope (as mandated by clause 4.19, for an example see annex C, clause C.5.15);
    • -
  • if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list.
    • -
-
-
    -
  • -

    Pagination logic shall be in place as mandated by clause 5.5.9.

    -
    • -

  • If in the process of obtaining the query result it is necessary to issue a Context Source discovery operation, the same Context Source filter input parameter (if present) shall be propagated.

    • -
  • -

    For each Attribute found in the target Entity, when datasetIdparameter is provided in the request:

    -
    • -
-
-
    -
  • Filter the Attribute instances based on the datasetIdparameter, i.e. keep only the Attribute instances whose datasetId is specified. The default Attribute instance is matched, if “@none” is specified.
    • -
  • If there is no Attribute instance whose datasetIdmatches the value of the parameter, the Attribute shall not be returned with the Entity.
    • -
-
-
-
    -
  • If the Accept Header is set to “application/json” or “application/ld+json”, a JSON-LD array is returned, representing the Entities as mandated by clause 5.2.4 and containing only the Attributes requested (if present).
    • -
-
-
-
    -
  • If the Prefer Header [26] is set to “ngsi-ld=<version>” then the ContextBroker shall endeavour to amend the elements of the JSON-LD array to conform to the specified version of the NGSI-LD specification as mandated in clause 4.3.6.8, and return a Preference-Applied Header set to “ngsi-ld=<conformant-version>” in the response.
    • -
-
-
-
    -
  • If the Accept Header is set to “application/geo+json”, the response shall be a GeoJSON FeatureCollection as mandated by clause 5.2.30, with each Feature within the FeatureCollection containing only the Attributes requested (if present):
    • -
-
-
-
    -
  • If the Prefer Header is omitted or set to “body=ld+json” then the FeatureCollection will also contain an @context field.
    • -
  • If the Prefer Header is set to “body=json“ the @context is sent as a Link Header and removed from the FeatureCollection object.
    • -
-
-

5.7.2.5 Output data

-

A JSON-LD array representing the matching entities as defined by clause 5.2.4 or in the case of GeoJSON requests a FeatureCollection as mandated by clause 5.2.30. If Entity ordering is specified (see clause 4.23), then the JSON-LD array or FeatureCollection returned shall be ordered according to the list of member names specified. For each matching Entity, only the Attributes specified by the Attribute list parameter shall be included. If such parameter is not present, then all Attributes shall be included.

-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be compacted according to the supplied @context.

-

If a language filter is specified and any of the returned Attributes corresponds to a LanguageProperty, the LanguageProperty in question shall be converted into a Property. The value of this Property shall correspond to the value of the string or strings from matching key-value pair of the languageMap where the key matches the language filter. A non-reified subproperty langshall be included in the response indicating the chosen language.

-

If no match can be made for a LanguageProperty, then the default identified by the JSON-LD “@none” shall be chosen if present, otherwise the choice of a single language is up to the implementation.

-

If inline Linked Entity retrieval (see clause 4.5.23.2) is specified, and any of the returned Attributes corresponds to an annotated Relationship, then unless a URI has been previously encountered, an entity subproperty shall also be included in the response holding the data for each URI corresponding to that Relationship’s target object URIs. If any of the returned Attributes corresponds to an annotated ListRelationship, then an entityList subproperty shall also be included in the response holding the ordered data corresponding to that ListRelationship’s target objectList URIs, unless a URI has been previously encountered.

-

If flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, the response shall be an array of JSON-LD objects representing the matching entities and the targets of their Relationships. If any of the returned Attributes corresponds to an annotated Relationship, unless a URI has been previously encountered, then data for each URI corresponding to the Relationship’s target object URIs is appended to the array. If any of the returned Attributes corresponds to an annotated ListRelationship, then an array of additional Linked Entities is appended to the array which hold the data corresponding to each of the URIs found within ListRelationship’s target objectList unless a URI has been previously encountered.

-

If the location of a previously generated EntityMap was passed into the request, or a flag to return an EntityMap was present in the request, the location of the EntityMap used in the operation shall be returned in a specific field in the response.

-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.3.1 Description

-

This operation allows retrieving the Temporal Evolution of an Entity.

-

5.7.3.2 Use case diagram

-

A Context Consumer can retrieve the Temporal Evolution of an Entity (in the form of a temporal representation) from an NGSI-LD system as shown in Figure 5.7.3.2‑1.

-
-

-
-
-

Figure 5.7.3.2-1: Retrieve Temporal Evolution of an Entity use case

-
-

5.7.3.3 Input data

-
    -
  • -

    Entity ID (URI) of the target Temporal Evolutionof an Entity to be retrieved.

    -
    • -
  • -

    List of Attribute (Properties or Relationships) names to be retrieved (projection attributes) (optional).

    -
    • -
  • -

    A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    An exclusionary list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    An NGSI-LD temporal query as mandated by clause 4.11 (optional).

    -
    • -
  • -

    A parameter (lastN) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional).

    -
    • -
  • -

    An optional JSON-LD context.

    -
    • -
  • -

    A flag indicating whether to return the location of the EntityMap used within the operation (optional).

    -
    • -

  • A suggested lifetime for the EntityMap, if EntityMap is to be created (optional).

    • -
  • -

    The location of a resource holding an EntityMap of matching Entity registrations (optional).

    -
    • -
  • -

    A datasetIdparameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).

    -
    • -
-

5.7.3.4 Behaviour

-
-
    -
  • If the Entity ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If projection attributes are present and indicate the use of Linked Entityretrieval, an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target Entity, because there is no existing Entity whose id (URI) is equivalent held locally, and no matching registrations apply, then an error of type ResourceNotFound shall be raised.
    • -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • The lastN parameter refers to a number, n, of Attribute instances which shall correspond to the last n timestamps (in descending ordering) of the temporal property (by default observedAt) within the concerned temporal interval.
    • -
  • Let S be the Temporal Evolution of theEntity as mandated by clause 5.2.20 with the specified Entity ID as it is available locally. S is empty in case no Temporal Evolution of the Entity is available locally.
    • -
  • From S, select only those Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by clause 4.11); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset.
    • -
  • If the ContextBroker implementation supports the use of EntityMaps then:
    • -
-
-
    -
  • -

    If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved:

    -
    -
      -

    • If the resource cannot be found, or the data has expired, a new EntityMap shall be created.

      • -

    • If the data has not expired, only the retrieved Entity Map shall be used to determine which Context Source Registrations match the Entity ID.

      • -
    • -
  • -

    If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created.

    -
    • -
-
-
    -
  • For Context Source Registrations that match the Entity ID and support the “retrieveTemporal” operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
-
-
-
    -
  • If an EntityMap is in use for this operation, and an EntityMap entry linked to a Context Source Registration is found, the location of the linked EntityMap shall be passed as part of any forwarded request.
    • -
  • For any exclusive, redirect and inclusive Context Source, the request is forwarded for remote retrieval by matching endpoints. and remote Attribute data for the Entity is received. The result is then merged together with S1 according to the algorithm defined in clause 4.5.5.
    • -
  • For any auxiliary Context Source Registrations the remote Attribute data received is added to S1 only when the Attribute instance, whose value of the timeproperty, which is used for the temporal query (observedAt as default), is not present in any of the Attribute instances received from elsewhere.
    • -
  • If an EntityMap is in use for this operation, the EntityMap’s linked maps are updated to hold the location of every EntityMap used by the Context Source Registrations.
    • -
-
-
-
    -
  • For the set of Attribute Instances that are in S1, when datasetIdparameter is provided in the request:
    • -
-
-
-
    -
  • Filter the Attribute instances based on the datasetIdparameter, i.e. keep only the Attribute instances whose datasetId is specified. The default Attribute instance is matched, if “@none” is specified.
    • -
  • If there is no Attribute instance whose datasetIdmatches the value of the parameter, remove the complete Attribute from S1.
    • -
-
-
-
    -
  • From the set of Attribute Instances that are in S1, include in their temporal representation only the Attribute instances (up to lastN) corresponding to the query’s projection Attributes, or aggregated values of Attribute instances (if aggregated temporal representation is requested).
    • -
-
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.7.3.5 Output data

-

A JSON-LD object representing the Temporal Evolution of the target Entity as mandated by clause 5.2.20.

-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

5.7.4 Query Temporal Evolution of Entities

-

5.7.4.1 Description

-

This operation allows querying the Temporal Evolution of Entities present in an NGSI-LD system. It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query.

-

5.7.4.2 Use case diagram

-

A Context Consumer can retrieve the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in Figure 5.7.4.2‑1.

-
-

-
-
-

Figure 5.7.4.2-1: Query Temporal Evolution of Entities use case

-
-

5.7.4.3 Input data

-
    -
  • -

    An NGSI-LD temporal query as mandated by clause 4.11.

    -
    • -
  • -

    A reference to a JSON-LD @context (optional).

    -
    • -
  • -

    A selector of Entity types as specified by clause 4.17 (optional). Both type name (short hand string) and fully qualified type name (URI) are allowed.

    -
    • -
  • -

    A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    An exclusionary list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    A list (one or more) of Entity identifiers (optional).

    -
    • -
  • -

    A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional).

    -
    • -
  • -

    An id pattern as a regular expression (optional).

    -
    • -
  • -

    An NGSI-LD query (to filter out Entities by Attribute values) as per clause 4.9 (optional).

    -
    • -
  • -

    An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by clause 4.10 (optional).

    -
    • -
  • -

    A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by clause 4.19 (optional).

    -
    • -
  • -

    An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties that describe them) as per clause 4.9 (optional).

    -
    • -
  • -

    A limit to the number of Entities to be retrieved. See clause 5.5.9.

    -
    • -
  • -

    A parameter (lastN) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional).

    -
    • -
  • -

    A specified language filter as per clause 4.15 (optional).

    -
    • -
  • -

    A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional).

    -
    • -
  • -

    A flag indicating whether to return the location of the EntityMap used within the operation (optional).

    -
    • -

  • A suggested lifetime for the EntityMap, if EntityMap is to be created (optional).

    • -
  • -

    The location of a resource holding an EntityMap of matching Entity registrations (optional).

    -
    • -
  • -

    A datasetId parameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).

    -
    • -
  • -

    A preferred ordering of Entities retrieved – only the Entity member name “id” can be used (Entity ordering attributes as defined by clause 4.23) (optional).

    -
    • -
  • -

    A preferred collation setting to be used when applying ordering of Entities (optional).

    -
    • -

  • A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional).

    -
    -

    In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

    -
    • -
-

5.7.4.4 Behaviour

-
-
    -
  • If a temporal query is not provided then an error of type BadRequestData shall be raised.
    • -
  • At least one of the following input data shall be provided:
    • -
-
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
-
    -
  • If projection attributes or filter conditions indicate the use of Linked Entityretrieval, an error of type BadRequestData shall be raised.
    • -
  • If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses 4.9 and 4.10) an error of type BadRequestData shall be raised.
    • -
  • If the ordering parameter is present and the execution of the operation is not limited to the local scope (see clause 5.5.13) then an error of type BadRequestData shall be raised.
    • -
  • If the ordering parameter is present and refers an entity name other than “id”, then an error of type BadRequestData shall be raised.
    • -
  • If a preferred collation setting is present and it does not conform to a valid ICU collation (see IETF RFC 6067 [36]) then an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of type and Attribute names shall be observed mandated by clause 5.5.7.
    • -
  • If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by clause 5.5.7.
    • -
  • The lastN parameter refers to a number, n, of Attribute instances which shall correspond to the last n timestamps (in descending ordering) of the temporal property (by default observedAt) within the concerned temporal interval.
    • -
  • Otherwise,
    • -
-
-
    -
  • -

    Let S be the set of selected Entities i.e. the query result set.

    -
    • -
  • -

    If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an Entity Array containing all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided):

    -
    -
      -

    • If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter.

      • -

    • If an id pattern is provided, keep in S only those Entities whose id matches the id pattern.

      • -

    • If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types.

      • -

    • From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by clause 4.11); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S4 be this new subset.

      • -
    • -
  • -

    Implementations shall run a query that shall return the Temporal Evolution of the matching Entities (all Entities stored locally, in case only a local scope is specified); the logical steps to select the final result set of Entities, and the Attribute instances included as part of their temporal representation, are enumerated as follows:

    -
    -
      -

    • If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter.

      • -

    • If an id pattern is provided, keep in S only those Entities whose id matches the id pattern.

      • -

    • If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types.

      • -

    • From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by clause 4.11); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset.

      • -

    • If a values filter query is provided, from S1, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by clause 4.9); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S2 be this new subset.

      • -

    • If no values filter query is provided, then S2 is equal to S1.

      • -

    • If geoquery is present, from S2, select those Entities whose GeoProperty instances meet the geospatial restrictions imposed by the geoquery (as mandated by clause 4.10); those geospatial restrictions shall be checked against the GeoProperty instances that are within the interval defined by the temporal query. Let S3 be this new subset.

      • -

    • If no geoquery is provided, then S3 is equal to S2.

      • -

    • If the Scope query is present, from S3, select those Entities whose Entity Scope instances match the Scope query (as mandated by clause 4.19, for an example see annex C, clause C.5.16). Let S4 be the new subset.

      • -

    • If no Scope query is provided, then S4 is equal to S3.

      • -
    • -
-
-
    -
  • If the ContextBroker implementation supports the use of EntityMaps then:
    • -
-
-
    -
  • -

    If the location of a resource holding an EntityMap of matching Entity registrations is present it shall be retrieved:

    -
    -
      -

    • If the resource cannot be found, or the data has expired, a new EntityMap shall be created.

      • -

    • If the data has not expired, only the retrieved EntityMap shall be used to determine which Context Source Registrations match the Entity ID.

      • -
    • -
  • -

    If a flag to return an EntityMap was present in the request, and no EntityMap currently exists, then a new EntityMap shall be created.

    -
    • -
-
-
    -
  • Unless local scope is specified (see clause 5.5.13), for Context Source Registrations that match the query and support the “queryTemporal” operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
-
-
    -
  • -

    If an EntityMap is in use for this operation, and an EntityMap entry linked to a Context Source Registration is found, the location of the EntityMap shall be passed as part of the forwarded request.

    -
    -
      -
    • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request. These filters then have to be applied after the Entity information from different Context Sources and local information, if there is any, has been aggregated.
      • -
    • -
  • -

    For any exclusive, redirect and inclusive Context Source Registrations that match against the query, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an Entity Array. The returned result is then merged into S4 according to the algorithm defined in clause 4.5.5.

    -
    • -
  • -

    For any auxiliary Context Source Registrations that match against the query, the request is forwarded for remote querying by matching endpoints. Data from the Entity Array received is merged only into S4 when an Attribute instance, whose value of the timeproperty used for the temporal query, is not already present in S4.

    -
    • -
-
-
    -
  • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, the following filters have to be applied on the aggregated Entities:
    • -
-
-
    -

  • If a values filter query is provided, from S4, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by clause 4.9); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S5 be this new subset.

    • -

  • If no values filter query is provided, then S5 is equal to S4.

    • -

  • If geoquery is present, from S5, select those Entities whose GeoProperty instances meet the geospatial restrictions imposed by the geoquery (as mandated by clause 4.10); those geospatial restrictions shall be checked against the GeoProperty instances that are within the interval defined by the temporal query. Let S6 be this new subset.

    • -

  • If no geoquery is provided, then S6 is equal to S5.

    • -

  • If the Scope query is present, from S6, select those Entities whose Entity Scope instances match the Scope query (as mandated by clause 4.19, for an example see annex C, clause C.5.16). Let S7 be the new subset.

    • -

  • If no Scope query is provided, then S7 is equal to S6.

    • -
-

<!-- -->

-
    -
  • -

    Otherwise S7 is equal to S4

    -
    • -
  • -

    If a datasetId parameter is provided, from S7, for all Entities, filter the Attribute instances based on the datasetIds specified in the parameter, i.e. keep only the Attribute instances whosedatasetId is specified. The default Attribute instance is matched, if “@none” is specified. Remove all Attributes without remaining Attribute instances. Let S8 be this new subset.

    -
    • -
  • -

    If no datasetId is provided then S8 equals to S7.

    -
    • -
  • -

    From the set of Entities that are in S8, include in their temporal representation only the Attribute instances (up to lastN) corresponding to the query’s projection Attributes, or aggregated values of Attribute instances (if aggregated temporal representation is requested), and which meet the temporal, query and geoquery restrictions.

    -
    -
    -

    If an aggregated temporal representation is requested and any of the requested Attributes is not eligible for at least one of the aggregation methods specified in the request parameters, then an error of type InvalidRequest shall be raised.

    -
    • -
  • -

    Pagination logic shall be in place as mandated by clause 5.5.9.

    -
    • -
  • -

    If in the process of obtaining the query result it is necessary to issue a Context Source discovery operation, the same Context Source filter input parameter (if present) shall be propagated.

    -
    • -
-

5.7.4.5 Output Data

-

A JSON-LD array representing the matching entities as defined by clause 5.2.21 and selected according to the behaviour described by clause 5.7.4.4.

-

If Entity ordering is specified (see clause 4.23), then the JSON-LD array returned shall be ordered according to the member names specified.

-

If a restrictive list of Entity member names is present, every Entity within the payload body is reduced down to only contain the defined Entity members.

-

If an exclusionary list of Entity member names is present, the defined Entity members listed are removed from each Entity within the payload.

-

5.7.5 Retrieve Available Entity Types

-

5.7.5.1 Description

-

This operation allows retrieving a list of NGSI-LD entity types for which entity instances exist within the NGSI-LD system.

-

5.7.5.2 Use case diagram

-

A Context Consumer can retrieve a list of NGSI-LD entity types from the system as shown in Figure 5.7.5.2‑1.

-
-

-
-
-

Figure 5.7.5.2-1: Retrieve Available Entity Types use case

-
-

5.7.5.3 Input data

-
-
    -
  • An optional JSON-LD context.
    • -
-
-

5.7.5.4 Behaviour

-
-
    -
  • Return a JSON-LD object representing the list of entity types, as mandated by clause 5.2.24, for which entity instances exist within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.
    • -
-
-

5.7.5.5 Output data

-

A JSON-LD object representing the list of available entity types, as mandated by clause 5.2.24.

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.6.1 Description

-

This operation allows retrieving a list with a detailed representation of NGSI-LD entity types for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided @context) and the attribute names that existing instances of this entity type have.

-

5.7.6.2 Use case diagram

-

A Context Consumer can retrieve a list with a detailed representation of NGSI-LD entity types from the system as shown in Figure 5.7.6.2‑1.

-
-

-
-
-

Figure 5.7.6.2-1: Retrieve Details of Available Entity Types use case

-
-

5.7.6.3 Input data

-
-
    -
  • An optional JSON-LD context.
    • -
-
-

5.7.6.4 Behaviour

-
-
    -
  • Return a list of JSON-LD objects representing the details of available entity types as mandated by clause 5.2.25 for which entity instances exist within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.
    • -
-
-

5.7.6.5 Output data

-

A list of JSON-LD objects representing the details of available entity types as mandated by clause 5.2.25.

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.7.1 Description

-

This operation allows retrieving detailed entity type information about a specified NGSI-LD entity type for which entity instances exist within the NGSI-LD system. The detailed representation includes the type name (as short name if available in the provided @context), the count of available entity instances and details about attributes that existing instances of this entity type have, including their name (as short name if available in the provided @context) and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty).

-

5.7.7.2 Use case diagram

-

A Context Consumer can retrieve a detailed representation of a specified NGSI-LD entity type from the system as shown in Figure 5.7.7.2‑1.

-
-

-
-
-

Figure 5.7.7.2-1: Retrieve Available Entity Type Information use case

-
-

5.7.7.3 Input data

-
-
    -
  • Entity type name for which detailed information is to be retrieved.
    • -
  • An optional JSON-LD context.
    • -
-
-

5.7.7.4 Behaviour

-
-
    -
  • Return a JSON-LD object representing the details of the specified entity type as mandated by clause 5.2.26, for which instances exist within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects.
    • -
-
-

5.7.7.5 Output data

-

A JSON-LD object representing the details of the specified entity type as mandated by clause 5.2.26.

-

5.7.8 Retrieve Available Attributes

-

5.7.8.1 Description

-

This operation allows retrieving a list of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system.

-

5.7.8.2 Use case diagram

-

A Context Consumer can retrieve a list of NGSI-LD attributes from the system as shown in Figure 5.7.8.2‑1.

-
-

-
-
-

Figure 5.7.8.2-1: Retrieve Available Attributes use case

-
-

5.7.8.3 Input data

-
-
    -
  • An optional JSON-LD context.
    • -
-
-

5.7.8.4 Behaviour

-
-
    -
  • Return a JSON-LD object representing the list of attributes as mandated by clause 5.2.27 that belong to entity instances existing within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.
    • -
-
-

5.7.8.5 Output data

-

A JSON-LD object representing the list of available attributes as mandated by clause 5.2.27.

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.9.1 Description

-

This operation allows retrieving a list with a detailed representation of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute.

-

5.7.9.2 Use case diagram

-

A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in Figure 5.7.9.2‑1.

-
-

-
-
-

Figure 5.7.9.2-1: Retrieve Details of Available Attributes use case

-
-

5.7.9.3 Input data

-

An optional JSON-LD context.

-

5.7.9.4 Behaviour

-

Return a list of JSON-LD objects representing the details of available attributes as mandated by clause 5.2.28 (restricted to the elements id, type, attributeName and typeNames) that belong to entity instances existing within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.

-

5.7.9.5 Output data

-

A list of JSON-LD objects representing the details of available attributes as mandated by clause 5.2.28 (restricted to the elements id, type, attributeName and typeNames).

-

5.7.10 Retrieve Available Attribute Information

-

5.7.10.1 Description

-

This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute, a count of available attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty).

-

5.7.10.2 Use case diagram

-

A context consumer can retrieve a list with a detailed representation of NGSI-LD attributes from the system as shown in Figure 5.7.10.2‑1.

-
-

-
-
-

Figure 5.7.10.2-1: Retrieve Available Attribute Information use case

-
-

5.7.10.3 Input data

-
-
    -
  • Name of the attribute for which detailed information is to be retrieved.
    • -
  • An optional JSON-LD context.
    • -
-
-

5.7.10.4 Behaviour

-

Return a JSON-LD object representing the details of available attributes as mandated by clause 5.2.28 that belong to entity instances existing within the NGSI-LD system. See clause 5.7.11 for architecture-related implementation aspects, in particular the distributed behaviour.

-

5.7.10.5 Output data

-

A JSON-LD object representing the details of available attributes as mandated by clause 5.2.28.

- -

Retrieving information about available types or attributes can be an expensive operation depending on the scale and architectural design decisions of the NGSI-LD system. This is in particular the case for retrieving the information about all available entity types and attributes related to all entity information available in an NGSI-LD system. Especially in the case of distributed architecture (clause 4.3.3) and federated architecture (clause 4.3.4) checking all entities can be so expensive that it can become practically infeasible.

-

Therefore, implementations may only take into account only information that is available or can be derived from a local datastore and the Context Registry, when implementing the retrieval of available entity types and attributes, as described in clauses 5.7.5, 5.7.6, 5.7.7, 5.7.8, 5.7.9 and 5.7.10. Context registrations do not always reflect which entity instances are actually available from a Context Source at a particular point in time, but only which entity instances are possibly available from a Context Source, thus in this case the information about available entity types and attributes is to be interpreted as “possibly available”. Also, context registrations can have different granularities, i.e. they possibly only contain entity type or attribute information, and thus the provided information about available entity types and attributes is possibly incomplete as a result. In particular the attributeNames in the EntityType data structure (clause 5.2.25), the attributeDetails in the EntityTypeInfo data structure (clause 5.2.26), and the attributeTypes and typeNames in the Attribute data structure (clause 5.2.27) may be provided as empty arrays if the information is not included in the respective context registration. Implementations may also provide estimates for the entity count or attribute count instead of the accurate count.

-

As an alternative to relying on local information only, the request can be forwarded to all Context Sources which support the respective operation according to the Context Source Registration describing them. In this case the returned lists are merged with the local list of entity types before returning them. This approach is more expensive but leads to a more accurate result.

-

5.8 Context Information Subscription

-

5.8.1 Create Subscription

-

5.8.1.1 Description

-

This operation allows creating a new subscription.

-

5.8.1.2 Use case diagram

-

A Context Subscriber can create a subscription to receive context updates within an NGSI-LD system as shown in Figure 5.8.1.2‑1.

-
-

-
-
-

Figure 5.8.1.2-1: Create subscription use case

-
-

5.8.1.3 Input data

-
-
    -
  • A data structure (represented in JSON-LD) conforming to the Subscription data type as mandated by clause 5.2.12.
    • -
-
-

5.8.1.4 Behaviour

-
-
    -
  • If the data types, cardinalities and restrictions expressed by clause 5.2.12 are not met, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint already knows about this Subscription, as there is an existing Subscription whose id (URI) is equivalent, an error of type AlreadyExists shall be raised.
    • -
  • If the subscription document does not include a Subscription identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation.
    • -
  • Then, implementations shall add a new Subscription. The behaviour for corresponding notifications shall be as per clause 5.8.6. The parameters of the created Subscription shall be configured as follows:
    • -
-
-
-
    -
  • The Subscription expiration date shall be equal to the value of the expiresAt member. If the expiration timestamp provided represents a moment before the current date and time, then an error of type BadRequestData shall be raised. If there is no expiresAt member the Subscription shall be considered as perpetual.
    • -
  • If the value of the isActive field is not included or is true then the initial status of the Subscription shall be set to “active”.
    • -
  • If the value of the isActive field is false, then the initial status of the Subscription shall be set to “paused”.
    • -
  • If present, the subscribed entities shall be those matching the conditions expressed under the EntitySelector, as defined in clause 5.2.33.
    • -
  • Watched Attributes shall be those Attributes (subject to clause 5.5.7 Term to URI expansion) pertaining to the subscribed entities (if present) and conveyed through the watchedAttributes member. Watched Attributes are those that trigger a new notification when they are changed. A non-present watchedAttributes member means that all Attributes shall be watched. If no subscribed entities have been specified, all entities with attributes matching at least one member of watchedAttributes are subscribed to.
    • -
  • The @context to be used for sending Notifications related to this Subscription shall be the one specified in the jsonldContext field. If not present, the jsonldContext field shall be initialized with the @context applicable for the Subscription (if @context is also not present in the Subscription, see clause 5.5.5). When the remote JSON-LD @context referenced by the jsonldContext field is not available implementations shall raise an error of type LdContextNotAvailable. If the remote JSON-LD @context referenced by the jsonldContext field is invalid, implementations shall raise an error of type BadRequestData.
    • -
  • Based on the content of the Subscription, a Context Source Registration Subscription shall be created (clause 5.11.2). The mapping of the id of the Subscription to the returned subscriptionId of the Context Source Registration Subscription shall be stored to enable updating or deleting the Context Source Registration Subscription in case of changes to the Subscription.
    • -
-
-
-
    -
  • If the subscription defines a timeInterval member, a Notification shall be sent periodically, when the time interval (in seconds) specified in such value field is reached, regardless of Attribute changes.
    • -
  • If timeInterval is not defined, whenever there is a change in the watched Attribute nodes (Properties or Relationships) of the concerned Entities, implementations shall post a new Notification as per the rules defined by clause 5.8.6.
    • -
  • If localOnly=false, each time a Context Source Notification with the subscriptionId of the previously created Context Source Registration Subscription is received, implementations shall do the following:
    • -
-
-
-
    -
  • For any exclusive, redirect and inclusive Context Source Registration received as part of the notification, implementation shall do the following depending on the triggerReason:
    • -
-
-
-
    -
  • If the triggerReason is “newlyMatching” and the Context Source Registration indicates support for the Create Subscription operation, a copy of the original Subscription shall be reduced to what is matched by the registration information. If the splitEntities member is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the members q, geoQ and scopeQ shall be removed from the created copy of the original Subscription. Also from the notification member, the attributes, pick and omit members are to be removed. The copied Subscription is then forwarded to the Context Source as a new Subscription where the notification endpoint is set to that of the local Broker. The mapping of the received subscriptionId with the own Subscription identifier is stored to enable forwarding received notifications to the original subscriber. In addition, a mapping of the id of the Context Source Registration to the received subscriptionId is stored, to enable updating or deleting the subscription in case of changes.
    • -
  • If the triggerReason is “updated” and the Context Source Registration indicates support for the Update Subscription operation, an update of the original Subscription, reduced to what is matched by the registration information, shall be created. If the splitEntities member is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the members q, geoQ and scopeQ shall be removed from the updated Subscription. Also from the notification member the attributes, pick and omit members are to be removed. The updated Subscription is then forwarded to the Context Source with the subscriptionId related to the Context Source Registration. As an optimization, an implementation may keep the originally forwarded Context Source Registration and compare with the new one to only forward the update, if there was a relevant change.
    • -
  • If the triggerReason is “noLongerMatching” and the Context Source Registration indicates support for the delete Subscription operation, a delete Subscription shall be forwarded to the Context Source with the subscriptionId related to the Context Source Registration.
    • -
-
-
-
    -
  • Implementations shall ensure that, when the Subscription expiration date is due, the status of the Subscription changes automatically to “expired”, so that notifications will no longer be sent.
    • -
-
-

5.8.1.5 Output data

-

A URI identifying the newly created Subscription.

-

5.8.2 Update Subscription

-

5.8.2.1 Description

-

This operation allows updating an existing subscription.

-

5.8.2.2 Use case diagram

-

A Context Subscriber can update an existing subscription within an NGSI-LD system as shown in Figure 5.8.2.2‑1.

-
-

-
-
-

Figure 5.8.2.2-1: Update subscription use case

-
-

5.8.2.3 Input data

-
-
    -
  • Subscription identifier (URI), the target subscription.
    • -
  • A JSON-LD document representing a Subscription Fragment.
    • -
-
-

5.8.2.4 Behaviour

-
-
    -
  • If the Subscription id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD System does not know about the target Subscription, because there is no existing Subscription whose id (URI) is equivalent, an error of type ResourceNotFound shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If the data types and restrictions expressed by clause 5.2.12 are not met by the Subscription Fragment, then an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • If the jsonldContext field is present and the referenced JSON-LD @context is not available, implementations shall raise an error of type LdContextNotAvailable. If the referenced JSON-LD @context is invalid, implementations shall raise an error of type BadRequestData.
    • -
  • Then, implementations shall modify the target Subscription as mandated by clause 5.5.8.
    • -
  • Finally, the following extra behaviour shall be observed when updating Subscriptions:
    • -
-
-
-
    -
  • If isActive is equal to true and expiresAt is not present, then status shall be updated to “active”, if and only if, the previous value of status was different than “expired”.
    • -
  • If isActive is equal to true and expiresAt corresponds to a DateTime in the future, then status shall be updated to “active”.
    • -
  • If isActive is equal to false and expiresAt is not present, then status shall be updated to “paused“, if and only if, the previous value of status was different than “expired”.
    • -
  • If only expiresAt is included and refers to a DateTime in the future, then status shall be updated to “active”, if and only if the previous value of status was “expired”.
    • -
  • If expiresAt is included but referring to a DateTime in the past, then a BadRequestData error shall be raised, regardless the value of isActive.
    • -
  • Based on the mapping of the Subscription to its respective Context Source Registration Subscription (see clause 5.8.1.4), that Context Source Registration Subscription shall be updated (clause 5.11.3).
    • -
-
-

5.8.2.5 Output data

-

None.

-

5.8.3 Retrieve Subscription

-

5.8.3.1 Description

-

This operation allows retrieving an existing subscription.

-

5.8.3.2 Use case diagram

-

A Context Subscriber can retrieve a specific subscription from an NGSI-LD system as shown in Figure 5.8.3.2‑1.

-
-

-
-
-

Figure 5.8.3.2-1: Retrieve subscription use case

-
-

5.8.3.3 Input data

-

Id (URI) of the subscription to be retrieved (target subscription).

-

5.8.3.4 Behaviour

-
-
    -
  • If the subscription Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the identifier provided does not correspond to any existing subscription in the system then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise implementations shall query the subscriptions and obtain the subscription data to be returned to the caller.
    • -
-
-

5.8.3.5 Output data

-

A JSON-LD object representing the subscription details as mandated by clause 5.2.12.

-

5.8.4 Query Subscriptions

-

5.8.4.1 Description

-

This operation allows querying existing Subscriptions.

-

5.8.4.2 Use case diagram

-

A Context Consumer can query the existent Subscriptions from an NGSI-LD system as shown in Figure 5.8.4.2‑1.

-
-

-
-
-

Figure 5.8.4.2-1: Query subscriptions use case

-
-

5.8.4.3 Input data

-

A limit to the number of subscriptions to be retrieved. See clause 5.5.9.

-

5.8.4.4 Behaviour

-
-
    -
  • The NGSI-LD system shall list all the existing subscriptions up to the limit specified as input data. If no limit is specified the number of subscriptions retrieved may depend on the implementation.
    • -
  • Pagination logic shall be in place as mandated by clause 5.5.9.
    • -
-
-

5.8.4.5 Output data

-

A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by clause 5.2.12.

-

5.8.5 Delete Subscription

-

5.8.5.1 Description

-

This operation allows deleting an existing subscription.

-

5.8.5.2 Use case diagram

-

A Context Subscriber can delete a subscription within an NGSI-LD system as shown in Figure 5.8.5.2‑1.

-
-

-
-
-

Figure 5.8.5.2-1: Delete subscription use case

-
-

5.8.5.3 Input data

-

A subscription identifier (URI).

-

5.8.5.4 Behaviour

-
-
    -
  • If the subscription Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the subscription id provided does not correspond to any existing subscription in the system then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise implementations shall delete the Subscription and no longer perform notifications concerning such Subscription.
    • -
  • Using the mapping of the own Subscription identifier to each of the subscriptionId of a subscription to a Context Source, a delete Subscription shall be forwarded to each such Context Source, if the delete Subscription operation is supported as indicated in the corresponding Context Source Registration:
    • -
-
-
-
    -
  • Based on the mapping of the Subscription to its respective Context Source Registration Subscription (see clause 5.8.1.4), that Context Source Registration Subscription shall be deleted (clause 5.11.6).
    • -
-
-

5.8.5.5 Output data

-

None.

-

5.8.6 Notification behaviour

-

A notification is a message that allows a subscriber to be aware of the changes in subscribed Entities. Implementations shall exhibit the following behaviour:

-
-
    -
  • Notifications shall only be sent if and only if the status of the corresponding subscription (subscription.status) is “active”, i.e. not”paused” nor “expired”.
    • -
  • If a Subscription defines a timeInterval member, a Notification shall be sent periodically, when the time interval (in seconds) specified in such value field is reached, regardless of Attribute changes. The notification message shall include all the subscribed Entities that match the query, geoquery and Scope query conditions. If none of query, geoquery and Scope query are defined, then all subscribed Entities shall be included. For each entity in the notification, only the Attribute instances are to be included that match the datasetId member in Subscription. If there are no matching Entities, no Notification is sent.
    • -
  • If a Subscription does not define a timeInterval term, the notification shall be sent whenever there is a change in the watched Attributes. An Attribute is considered to change when any of the members (including children) in its corresponding JSON-LD node is updated with a value different than the existing one. The notification message shall include all the subscribed Entities that changed and that match (as mandated by clauses 4.9, 4.10 and 4.19) the query, geoquery and Scope query conditions. If query, geoquery and scopeQuery are all not defined then all subscribed Entities that changed shall be included. If, for an Entity, there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions. For each entity in the notification, only the Attribute instances are to be included that match the datasetId member in Subscription. Finally, if a Context Source filter is defined, then only the subscribed Entities whose origin Context Source matches the referred filter shall be included.
    • -
  • If a Notification with a subscriptionId is received that has a mapping to a local Subscription identifier, the Notification shall be copied. If the splitEntities member of the local Subscription is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities,
    • -
-
-
-
    -
  • the Entities contained in the data member of the Notification shall be retrieved locally and from all Context Sources that have information about these Entities, except for the one from which the Notification has been received.
    • -
  • The retrieved Entities then shall be merged with the Entities in the data member.
    • -
  • All Entities that do not match the query, geoquery and Scope query conditions of the local Subscription shall be removed from the data member.
    • -
-
-
-
    -
  • If there are Entities in the data member of the Notification copy, the Notification copy shall be forwarded to the Notification endpoint specified in the local Subscription, using this local Subscription identifier instead of the subscriptionId received.
    • -
  • A Notification shall be sent as follows:
    • -
-
-
-
    -
  • The structure of the notification message shall be as mandated by clause 5.3.1.
    • -
  • The @context to be used is the one specified in the jsonldContext field of the corresponding Subscription.
    • -
  • The Attributes included (Properties or Relationships) shall be those specified by the notification.attributes member in the Subscription data type (clause 5.2.12). Term to URI expansion shall be observed (clause 5.5.7). The absence of the notification.attributes member of a Subscription means that all Attributes shall be included. If the notification was triggered by the deletion of an Entity and the notification.showChanges member is not set to true, only the deletedAt system property shall be provided. In case notification.sysAttrs is set to true, also createdAt and modifiedAt shall be provided.
    • -
  • If an Attribute has been deleted, only the name of the attribute as key and the URI “urn:ngsi-ld:null” as value shall be provided, unless more information is required. The latter is the case, if:
    • -
-
-
-
    -
  • a datasetId needs to be provided;
    • -
  • the notification.sysAttrs is set to true and thus the system generated sub-attributes (see clause 4.8) have to be provided;
    • -
  • notification.showChanges is set to true and thus a previous value or object has to be provided.
    • -
-
-
-

In all such cases, a JSON object with all the required information is provided, where the value or the object is set to the URI “urn:ngsi-ld:null” respectively or, in case of a LanguageProperty, the languageMap is set to {“@none”: “urn:ngsi-ld:null”}.

-
-
-
    -
  • If the notification.formatmember value is set, the representation of the entities changes:
    • -
-
-
-
    -
  • If the notification.format is set to “concise”then a concise representation of the entities shall be provided as defined by clause 4.5.1.
    • -
  • If the notification.format is set to “simplified” (or “keyValues” as a synonym), then a simplified representation of the entities (as mandated by clause 4.5.4) shall be provided.
    • -
  • Otherwise the normalized format as defined by clause 4.5.1 shall be used.
    • -
-
-
-
    -
  • If the notification.pickmember value is set, every Entity within the payload body is reduced down to only contain the defined entity members listed.
    • -
  • If the notification.omitmember value is set, the defined entity members listed are removed from each Entity within the payload.
    • -
  • If the notification.joinmember value is set then Linked Entityretrieval(as mandated by clause 4.5.23) shall be provided.
    • -
  • If the ngsildConformance field of the corresponding Subscription is set, the notification shall undergo a backwards compatibility operation as defined by clause 4.3.6.8 and be amended to conform to the supplied version of the NGSI-LD specification.
    • -
  • A Notification shall be sent (as mandated by each concrete binding and including any optional endpoint.receiverInfodefined by clause 5.2.22) to the endpoint specified by the endpoint.urimember of the notification structure defined by clause 5.2.14. The Notification content shall be JSONby default. However, this can be changed to JSON-LD or GeoJSONby means of the endpoint.acceptmember.
    • -
  • The notification.timesSent member shall be incremented by one.
    • -
  • The notification.lastNotification member shall be updated with a timestamp representing the current date and time.
    • -
  • If the response to the notification request is 200 OK then implementations shall:
    • -
-
-
-
    -
  • Update notification.lastSuccess with a timestamp representing the current date and time.
    • -
  • Update notification.status to “ok”.
    • -
-
-
-
    -
  • If the response to the notification request is different than 200 OKthen implementations shall:
    • -
-
-
-
    -
  • Update notification.lastFailure with a timestamp representing the current date and time.
    • -
  • Update notification. Status to “failed”.
    • -
-
-

5.9 Context Source Registration

-

5.9.1 Introduction

-

As described in clause 5.2.9, Context Source Registrations have a similar structure as Entities and are generally handled in the same way. However, there are some aspects that are specific to Registrations, in particular with respect to the handling of required properties. Thus, the operation descriptions for Registrations reference the respective operations for Entities and in addition specify any deviations and additions that are necessary for handling Context Source Registrations.

-

Context Source Registrations either contain information about Context Sources providing the latest information or about Context Sources providing temporal information, but not both. Context Sources that can provide both thus have to use two separate Context Source Registrations. If no temporal query is present, only Context Source Registrations for Context Sources providing latest information are returned, i.e. those which do not specify time intervals used for temporal queries. If a temporal query is present in a request for Context Source Registrations, only those Context Source Registrations that have a matching time interval are returned.

-

5.9.2 Register Context Source

-

5.9.2.1 Description

-

This operation allows registering a context source within an NGSI-LD system.

-

5.9.2.2 Use case diagram

-

A Context Provider can register one or more context sources within an NGSI-LD system as shown in Figure 5.9.2.2‑1.

-
-

-
-
-

Figure 5.9.2.2-1: Register context source use case

-
-

5.9.2.3 Input data

-

A data structure conforming to the CSourceRegistration data type as mandated by clause 5.2.9.

-

5.9.2.4 Behaviour

-

Implementations shall generally exhibit the behaviour described in clause 5.6.1.4, but instead of any type of entities only Context Source Registrations can be provided and the following exceptions shall apply:

-
-
    -
  • If the data types and restrictions expressed by clause 5.2.9 are not met by the Context Source Registration, then an error of type BadRequestData shall be raised.
    • -
  • If a contextSourceInfo array is defined and the restrictions expressed by clause 4.3.6.6 are not met by the Context Source Registration, then an error of type BadRequestData shall be raised.
    • -
  • If the Context Source to be registered has its mode property defined as exclusive, the following additional restrictions apply:
    • -
-
-
-
    -
  • If an exclusive or redirect Context Source Registration already matches against the Entity ID (URI) and any of the Attributes defined in the registration, an error of type Conflict shall be raised.
    • -
  • If an Entity already exists for the supplied Entity ID (URI) and the existing Entity contains any of the Attributes defined in the registration, an error of type Conflict shall be raised.
    • -
-
-
-
    -
  • If the Context Source to be registered has its mode property defined as redirect, the following additional restriction applies:
    • -
-
-
-
    -
  • If an existing Entity already matches the Context Source Registration, an error of type Conflict shall be raised.
    • -
-
-
-
    -
  • If the Context Source to be registered has its mode property defined as auxiliary, the following additional restriction applies:
    • -
-
-
-
    -
  • If the operations property is not defined as one of: “retrieveOps”, “retrieveEntity” or “queryEntity”, or a combination thereof, an error of type BadRequestData shall be raised.
    • -
-
-
-
    -
  • If the property expiresAt is not defined then the Context Source Registration shall last forever (or until it is deleted from the system).
    • -
  • If expiresAt is a date and time in the past, an error of type BadRequestData shall be raised.
    • -
  • If expiresAt is a date and time in the future, implementations shall delete the Registration when this point in time is reached.
    • -
  • If the NGSI-LD endpoint knows about this Context Source Registration,as there is an existing Context Source Registrationwhose id (URI) is equivalent, an error of type AlreadyExists shall be raised.
    • -
  • If the subscription document does not include a Context Source Registration identifier, a new identifier (URI) shall be automatically generated by the implementation.
    • -
  • Implementations shall add the concerned Context Source Registration and return an ‘ok’ response together with a registration identifier (id).
    • -
  • This id shall be used if NGSI-LD clients need to manage the registration later.
    • -
-
-

5.9.2.5 Output data

-

A URI identifying the newly created ContextSourceRegistration.

-

5.9.3 Update Context Source Registration

-

5.9.3.1 Description

-

This operation allows updating a Context Source Registration in an NGSI-LD system.

-

5.9.3.2 Use case diagram

-

A Context Provider can update a Context Source Registration in an NGSI-LD system as shown in Figure 5.9.3.2‑1.

-
-

-
-
-

Figure 5.9.3.2-1: Update context source registration use case

-
-

5.9.3.3 Input data

-
-
    -
  • Context Source Registration identifier (URI), the target Context Source Registration.
    • -
  • A JSON-LD document representing a Context Source Registration Fragment (clause 5.4).
    • -
-
-

5.9.3.4 Behaviour

-
-
    -
  • If the target Context Source Registration id (id) is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If a “contextSourceInfo” array is defined and the restrictions expressed by clause 4.3.6.6 are not met by the Context Source Registration, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD System does not know about the target Context Source Registration, because there is no existing Context Source Registration whose id (URI) is equivalent, an error of type ResourceNotFound shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If the data types and restrictions expressed by clause 5.2.9 are not met by the Context Source Registration Fragment, then an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • If the Context Source Registration to be updated has its mode property defined as exclusive, the following additional restrictions apply:
    • -
-
-
-
    -
  • If an exclusive or redirect Context Source Registration already matches against the Entity ID (URI) and any of the Attributes defined in the registration, an error of type Conflict shall be raised.
    • -
  • If an Entity already exists for the supplied Entity ID (URI) and the existing Entity contains any of the Attributes defined in the registration, an error of type Conflict shall be raised.
    • -
-
-
-
    -
  • If the Context Source Registration to be updated has its mode property defined as redirect, the following additional restriction applies:
    • -
-
-
-
    -
  • If an existing Entity already matches the Context Source Registration, an error of type Conflict shall be raised.
    • -
-
-
-
    -
  • If the Context Source to be updated has its mode property defined as auxiliary, the following additional restriction applies:
    • -
-
-
-
    -
  • If the operations property is not defined as one of: “retrieveOps”, “retrieveEntity” or “queryEntity”, an error of type BadRequestData shall be raised.
    • -
-
-
-
    -
  • Then, implementations shall modify the target Context Source Registration as mandated by clause 5.5.8.
    • -
-
-

5.9.3.5 Output data

-

None.

-

5.9.4 Delete Context Source Registration

-

5.9.4.1 Description

-

This operation allows deleting a Context Source Registration from an NGSI-LD system.

-

5.9.4.2 Use case diagram

-

A context provider can delete a context source registration from an NGSI-LD system as shown in Figure 5.9.4.2‑1.

-
-

-
-
-

Figure 5.9.4.2-1: Delete context source registration use case

-
-

5.9.4.3 Input data

-

Registration identifier (URI) of the context source registration to be deleted (target registration).

-

5.9.4.4 Behaviour

-
-
    -
  • If the target context source registration id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target context source registration, because there is no existing context source registration whose id (URI) is equivalent, then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise the context source registration shall be removed.
    • -
-
-

5.9.4.5 Output data

-

None.

-

5.10 Context Source Discovery

-

5.10.1 Retrieve Context Source Registration

-

5.10.1.1 Description

-

This operation allows retrieving a specific context source registration from an NGSI-LD system.

-

5.10.1.2 Use case diagram

-

A context consumer or a context provider can retrieve a specific context source registration from an NGSI-LD system as shown in Figure 5.10.1.2‑1.

-
-

-
-
-

Figure 5.10.1.2-1: Retrieve context source registration use case

-
-

5.10.1.3 Input data

-

Context source registration identifier (id) of the context source registration to be retrieved (target registration).

-

5.10.1.4 Behaviour

-
-
    -
  • If the context source registration id (id) is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about the target context source registration, because there is no existing context source registration whose id (URI) is equivalent, then an error of type ResourceNotFound shall be raised.
    • -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • Otherwise return a JSON-LD object representing the Context Source Registration as mandated by clause 5.2.9.
    • -
-
-

5.10.1.5 Output data

-

A JSON-LD object representing the target context source registration as mandated by clause 5.2.9.

-

5.10.2 Query Context Source Registrations

-

5.10.2.1 Description

-

This operation allows discovering context source registrations from an NGSI-LD system. The behaviour of the discovery of context source registrations differs significantly from the querying of entities as described in clause 5.7.2. The approach is that the client submits a query for entities as described in clause 5.7.2, but instead of receiving the Entity information, it receives a list of Context Source Registrations describing Context Sources that possibly have some of the requested Entity information. This means that the requested Entities and Attributes are matched against the ‘information’ property as described in clause 5.12.

-

If no temporal query is present, only Context Source Registrations for Context Sources providing latest information, i.e. without specified time intervals, are considered. If a temporal query is present only Context Source Registrations with matching time intervals, i.e. observationInterval or managementInterval, are considered.

-

5.10.2.2 Use case diagram

-

A Context Consumer can discover context source registrations that may be able to provide (part of) the context information specified in the query from an NGSI-LD system as shown in Figure 5.10.2.2‑1.

-
-

-
-
-

Figure 5.10.2.2-1: Discover context source registrations use case

-
-

5.10.2.3 Input data

-
-
    -
  • A reference to a JSON-LD @context (optional).
    • -
  • A selector of Entity types as specified by clause 4.17. Both type name (short hand string) and fully qualified type name (URI) are allowed (optional).
    • -
  • A list (one or more) of Entity identifiers (optional).
    • -
  • A list (one or more) of Attribute names (called query projection attributes) (optional).
    • -
  • An id pattern as a regular expression (optional).
    • -
  • An NGSI-LD query (to filter out Entities by Attribute values, used here to identify relevant attributes) as per clause 4.9 (optional).
    • -
  • An NGSI-LD geoquery (to filter out Entities by spatial relationships, used here to identify relevant GeoProperties and for geographical scoping) as per clause 4.10 (optional).
    • -
  • In the case of GeoJSON representation:
    • -
-
-
-
    -
  • The name of the GeoProperty attribute to use as the geometry for the GeoJSON representation as mandated by clause 4.5.16 (optional).
    • -
  • A datasetId specifying which instance of the value is to be selected if the GeoProperty value has multiple instances as defined by clause 4.5.5 (optional).
    • -
-
-
-
    -
  • An NGSI-LD temporal query as per clause 4.11 (optional).
    • -
  • An NGSI-LD context source query as per clause 4.9 (optional).
    • -
  • A NGSI-LD Scope query as mandated by clause 4.19 (optional).
    • -
  • A limit to the number of Context Source Registrations to be retrieved. See clause 5.5.9.
    • -
  • A specified language filter as per clause 4.15 (optional).
    • -
-
-

It is not possible to retrieve a set of context source registrations related to entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via lists of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery.

-

5.10.2.4 Behaviour

-
-
    -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • At least one of the following input data shall be provided:
    • -
-
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names;
    2. -
-
-
-
    -
  1. NGSI-LD Query;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery.
    2. -
-
-
-

If none of them is provided, then an error of type BadRequestData shall be raised (too wide query). Attributes specified in NGSI-LD Query or NGSI-LD GeoQuery shall be used for matching RegistrationInfo elements in the same way as the attributes in the list of Attribute names.

-
-
-
    -
  • If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or temporal query are not syntactically valid (as per clauses 4.9, 4.10 and 4.11) an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of type and Attribute names shall be performed, as mandated by clause 5.5.7.
    • -
  • Otherwise, implementations shall run a query that shall return context source registrations that meet all the applicable conditions:
    • -
-
-
-
    -
  • If present, the entity specification in the query consisting of a combination of entity type selector and entity id/entity id pattern (optional) matches an EntityInfo specified in a RegistrationInfo of the information property in a context source registration. If there is no EntityInfo specified in the RegistrationInfo, the entity specification is considered matching. This matching is further described in clause 5.12.
    • -
  • If present, at least one Attribute name specified in the query matches one Property or Relationship in the RegistrationInfo element of the information property in a context source registration. If no Properties or Relationships are specified in the RegistrationInfo, the Attribute names are considered matching. This matching is further described in clause 5.12.
    • -
  • If present, the geoquery is matched against the GeoProperty identified in the geoquery. If no GeoProperty is specified in the geoquery, the default property is location. The geoquery matches the GeoProperty specified in the Context Source Registration, if the location directly matches or if the location possibly contains locations that would match the geoquery.
    • -
  • If no temporal query is present, only Context Source Registrations for Context Sources providing latest information, i.e. without specified time intervals, are considered.
    • -
  • If a temporal query is present, only Context Source Registrations with specified time intervals, i.e. observationInterval or managementInterval are considered. If the timeproperty is observedAt or no timeproperty is specified in the temporal query (default: observedAt), the temporal query is matched against the observationInterval (if present). If the timeproperty is createdAt, modifiedAt or deletedAt, the temporal query is matched against the managementInterval (if present). If the relevant interval is not present, there is no match:
    • -
-
-
-
    -
  • The semantics of the match is that the timeAt in the case of the “before” and “after” relation is contained in or is an endpoint of a time period included in the specified time interval. In the case of the “between” relation there is a match if there is an overlap between the interval specified by the timeAt and endTimeAt and the specified time interval.
    • -
-
-
-
    -
  • If present, the conditions specified by the context source query filter match the respective Context Source Properties (as mandated by clause 4.9).
    • -
  • If present, the Scope query (as mandated by clause 4.19) is matched against the scope property.
    • -
-
-
-
    -
  • Pagination logic shall be in place as mandated by clause 5.5.9.
    • -
-
-

5.10.2.5 Output data

-

A JSON-LD array of matching Context Source Registrations as defined by clause 5.2.9. Instead of the original Context Source Registration which may contain a lot of irrelevant information, implementations should return filtered Context Source Registrations, which only contain context source registration information relevant for the query, in particular only matching RegistrationInfo elements.

-

5.11 Context Source Registration Subscription

-

5.11.1 Introduction

-

Context Source Registration Subscriptions in general work like context information subscriptions; however, instead of resulting in notifications with context information, the notifications contain Context Source Registrations describing Context Sources that can potentially provide the requested context information. If no temporal query is present, only Context Source Registrations for Context Sources providing latest information, i.e. without such time intervals, are considered. If a temporal query is present only Context Source Registrations with matching time intervals, i.e. observationInterval or managementInterval, are considered.

-

5.11.2 Create Context Source Registration Subscription

-

5.11.2.1 Description

-

This operation allows creating a new Context Source Registration Subscription.

-

5.11.2.2 Use case diagram

-

A Context Source Subscriber can subscribe to a new Context Source Registration as shown in Figure 5.11.2.2‑1.

-
-

-
-
-

Figure 5.11.2.2-1: Subscribe Context Source Registration use case

-
-

5.11.2.3 Input data

-
-
    -
  • A data structure (represented in JSON-LD) conforming to the Subscription data type as mandated by clause 5.2.12.
    • -
-
-

5.11.2.4 Behaviour

-
-
    -
  • The behaviour shall be as described in clause 5.8.1.4, restricted to the local case (where Subscriptions cannot be received from remote Brokers), with the following exceptions:
    • -
-
-
-
    -
  • If all checks described in clause 5.8.1.4 pass, implementations shall add a new Context Source Registration Subscription. The parameters of the created subscription shall be configured as described in clause 5.2.12.
    • -
  • Instead of directly matching the entities and watched Attributes from the Subscription with the Context Source registrations, the entities specified in the subscription, the watched Attributes and the Attributes specified in the notification parameter are matched against the respective information property of the Context Source registrations. If either the watched Attributes or the Attributes in the notification are not present or of length 0, all possible Attributes (if present in the Context Source Registrations) for matching entities match. This matching is further described in clause 5.12.
    • -
  • If present, the geoquery in the geoQ element is matched against the GeoProperty of the subscription identified in the geoQ element. If no GeoProperty is specified in the geoquery, the default property is ‘location’. The geoquery matches the GeoProperty specified in the Context Source Registration, if the location directly matches or if the location possibly contains locations that would match the geoquery.
    • -
  • If no temporal query is present in the temporalQ element, only Context Source Registrations for Context Sources providing latest information, i.e. without specified time intervals for observationInterval or managementInterval, are considered.
    • -
  • If a temporal query in the temporalQ element is present, only Context Source Registrations with specified time intervals are considered. If the timeproperty is “observedAt” or no timeproperty is specified in the temporal query (default: observedAt), the temporal query is matched against the observationInterval (if present). If the timeproperty is “createdAt”, “modifiedAt”or “deletedAt”, the temporal query is matched against the managementInterval (if present). If the relevant interval is not present, there is no match:
    • -
-
-
-
    -
  • The semantics of the match is that the timeAt in the case of the “before” and “after” relation is contained in or is an endpoint of a time period included in the specified time interval. In the case of the “between” relation there is a match if there is an overlap between the interval specified by the timeAt and endTimeAt and the specified time interval.
    • -
-
-
-
    -
  • If present, the conditions specified by the context source filter match the respective Context Source Properties (as mandated by clause 4.9).
    • -
-
-
-
    -
  • If the subscription defines a timeInterval term, a CsourceNotification (clause 5.3.2) with all matching Context Source Registrations shall be sent periodically, initially on subscription and when the time interval (in seconds) specified in such value field is reached, independent of any changes to the set of Context Source registrations.
    • -
  • If timeInterval is not defined, initially on subscription and whenever there is a change of a matching Context Source Registration (creation, update, deletion), implementations shall post a new CsourceNotification to the endpoint specified in the notification parameters informing about this change by providing the Context Source Registration(s) together with the appropriate trigger reason in the triggerReason member.
    • -
  • If present, the conditions specified by the context source query match the respective Context Source Properties (as mandated by clause 4.9).
    • -
  • If present, the Scope query (as mandated by clause 4.19) is matched against the scope property.
    • -
-
-

5.11.2.5 Output data

-

A URI identifying the newly created Subscription.

-

5.11.3 Update Context Source Registration Subscription

-

5.11.3.1 Description

-

This operation allows updating an existing Context Source Registration Subscription.

-

5.11.3.2 Use case diagram

-

A context source subscriber can update a Context Source Registration Subscription as shown in Figure 5.11.3.2‑1.

-
-

-
-
-

Figure 5.11.3.2-1: Update Context Source Registration Subscription use case

-
-

5.11.3.3 Input data

-
-
    -
  • Subscription identifier (URI), the target Context Source Registration Subscription.
    • -
  • A JSON-LD document representing a Subscription Fragment.
    • -
-
-

5.11.3.4 Behaviour

-
-
    -
  • If the Subscription Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the data types and restrictions expressed by clause 5.2.12 are not met by the Subscription Fragment, then an error of type BadRequestData shall be raised.
    • -
  • Then, implementations shall modify the target subscription as mandated by clause 5.5.8.
    • -
  • Finally, send a notification with all currently matching Context Source Registrations.
    • -
-
-

5.11.3.5 Output data

-

None.

-

5.11.4 Retrieve Context Source Registration Subscription

-

5.11.4.1 Description

-

This operation allows retrieving an existing Context Source Registration Subscription.

-

5.11.4.2 Use case diagram

-

A Context Source subscriber can retrieve a specific Context Source Registration Subscription as shown in Figure 5.11.4.2‑1.

-
-

-
-
-

Figure 5.11.4.2-1: Retrieve Context Source Registration Subscription use case

-
-

5.11.4.3 Input data

-

Id (URI) of the subscription to be retrieved (target subscription).

-

5.11.4.4 Behaviour

-
-
    -
  • If the subscription Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the identifier provided does not correspond to any existing subscription in the system then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise implementations shall query the Context Source Registration Subscriptions and obtain the subscription data to be returned to the caller.
    • -
-
-

5.11.4.5 Output data

-

A JSON-LD object representing the subscription details as mandated by clause 5.2.12.

-

5.11.5 Query Context Source Registration Subscriptions

-

5.11.5.1 Description

-

This operation allows querying existing Context Source Registration Subscriptions.

-

5.11.5.2 Use case diagram

-

A context source subscriber can query all existing Context Source Registration Subscriptions as shown in Figure 5.11.5.2‑1.

-
-

-
-
-

Figure 5.11.5.2-1: Query Context Source Registration Subscriptions use case

-
-

5.11.5.3 Input data

-

A limit to the number of Context Source Registration Subscriptions to be retrieved. See clause 5.5.9.

-

5.11.5.4 Behaviour

-
-
    -
  • The NGSI-LD System shall list all the existing Context Source Registration Subscriptions.
    • -
  • Pagination logic shall be in place as mandated by clause 5.5.9.
    • -
-
-

5.11.5.5 Output data

-

A list (represented as a JSON array) of JSON-LD objects each one representing subscription details as mandated by clause 5.2.12.

-

5.11.6 Delete Context Source Registration Subscription

-

5.11.6.1 Description

-

This operation allows deleting an existing Context Source Registration Subscription.

-

5.11.6.2 Use case diagram

-

A context source subscriber can delete a Context Source Registration Subscription as shown in Figure 5.11.6.2‑1.

-
-

-
-
-

Figure 5.11.6.2-1: Delete Context Source Registration Subscriptions use case

-
-

5.11.6.3 Input data

-
-
    -
  • A subscription identifier (URI).
    • -
-
-

5.11.6.4 Behaviour

-
-
    -
  • If the subscription Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the subscription id provided does not correspond to any existing subscription in the system then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise implementations shall delete the Context Source Registration Subscription and no longer perform notifications concerning that Subscription.
    • -
-
-

5.11.6.5 Output data

-

None.

-

5.11.7 Notification behaviour

-

A Context Source Notification is a message that allows a subscriber to be aware of the changes in the set of Context Source Registrations describing Context Sources that can potentially provide the requested context information. Implementations shall exhibit the behaviour described in clause 5.8.6 with the following exceptions:

-
-
    -
  • If a subscription defines a timeInterval member, a CsourceNotification (clause 5.3.2) shall be sent on initial subscription and periodically, when the time specified time interval (in seconds) has elapsed, regardless of any changes to the set of context source registrations. The CsourceNotification message shall include all the Context Source Registrations whose information property matches the entities and watched Attributes or Attributes specified in the notification parameter and, if present, have a matching geoquery. If either the watched Attributes or the Attributes in the notification are not present or of length 0, all possible Attributes (if present in the Context Source Registrations) for fitting entities match.
    • -
  • If a subscription does not define a timeInterval term, the csource notification shall be sent on initial subscription and whenever there is a change in a matching csource registration. Such a change may be triggered by the creation of a new matching csource registration, the update of a csource registration (whether matching before the update, after the update or in both cases) or the deletion of a matching csource registration. The notification message shall include the matching csource registration(s) together with the appropriate trigger reason in the triggerReason member.
    • -
  • Instead of providing the original Context Source Registration which may contain a lot of irrelevant information, implementations should return filtered Context Source Registrations, which only contain context source registration information relevant for the subscription, in particular only matching RegistrationInfo elements.
    • -
  • A csource notification shall be sent as follows:
    • -
-
-
-
    -
  • The structure of the csource notification message shall be as mandated by clause 5.3.2.
    • -
  • A csource notification shall be sent to the endpoint.
    • -
  • The notification.timesSent member shall be incremented by one.
    • -
  • The notification.lastNotification member shall be updated with the current timestamp.
    • -
  • If the notification is sent successfully:
    • -
-
-
-
    -
  • Update notification.lastSuccess with the current timestamp.
    • -
-
-
-
    -
  • If the notification is not sent successfully:
    • -
-
-
-
    -
  • Update notification.lastFailure with the current timestamp.
    • -
  • Update the subscription status to “failed”.
    • -
-
-

5.12 Matching Context Source Registrations

-

When querying Context Source Registrations as described in clause 5.10.2 and subscribing to Context Source Registrations as described in clause 5.11.2, the Entities and/or Attributes specified in the request have to be matched against the set of Context Source Registrations, extracting the matching ones. This clause describes this matching.

-

The relevant specification information in the query for Context Source Registrations are the selector of Entity Types (if present), the list of Entity identifiers (if present), the id pattern (if present) and the list of Attribute names (if present). In the case of subscriptions to Context Source Registrations, it is the Entities as specified in the array of type EntitySelector in the Subscription, the watchedAttributes element of the Subscription and the attributes specified as part of the NotificationParams element of the Subscription. If the attributes in the NotificationParams element are empty or not present, the matching is done as if no attribute identifiers have been specified, otherwise the combination of the watchedAttributes and the attributes in the NotificationParams element are used as the specified attribute identifiers for the matching.

-

Even though the way relevant Entities are specified differs in queries and subscriptions, they consist of the same information, so for the purpose of this clause, the specification of Entity Types or Attributes refers to the relevant elements for matching, i.e. Entity Types, Entity identifiers, id pattern and Attribute names. A specification of Entity Types or Attributes shall contain at least one of:

-
-
    -
  1. selector of Entity Types; or
    2. -
  2. list of Attribute names.
    3. -
-
-

A specification of Entity Types or Attributes matches a Context Source Registration if at least one of the RegistrationInfo elements in the information element matches. An Entity specification matches a RegistrationInfo if the following conditions hold:

-
-
    -
  • If present, the selector of Entity Types, Entity identifiers and id pattern match at least one of the EntityInfo elements of the RegistrationInfo (see below).
    • -
  • If present, the Attribute identifiers match the combination of Properties and Relationships specified in the RegistrationInfo (see below).
    • -
-
-

An Entity specification consisting of selector of Entity Types, Entity identifiers and id pattern matches an EntityInfo element of the RegistrationInfo if the type selector matches the entity types in the EntityInfo element and one of the following conditions holds:

-
-
    -
  • The EntityInfo contains neither an id nor an idPattern.
    • -
  • One of the specified Entity identifiers matches the id in the EntityInfo.
    • -
  • At least one of the specified Entity identifiers matches the idPattern in the EntityInfo.
    • -
  • The specified id pattern matches the id in the EntityInfo.
    • -
  • Both a specified id pattern and an idPattern in the Entity Info are present (since in the general case it is not easily feasible to determine if there can be identifiers matching both patterns).
    • -
-
-

Attribute names match the combination of Properties and Relationships if one of the following conditions hold:

-
-
    -
  • No Attribute names have been specified (as this means all Attributes are requested).
    • -
  • The combination of Properties and Relationships is empty (as this means only Entities have been registered and the Context Sources may have matching Property or Relationship instances).
    • -
  • If at least one of the specified attribute names matches a Property or Relationship specified in the RegistrationInfo.
    • -
-
-

If the request that triggered the matching includes a datasetId parameter and the CSourceRegistration to be matched contains a datasetId element, the CSourceRegistration should only be considered matching, if both have at least one value in common. If only one of them specifies a datasetId, it is considered a match.

-

In the case of distributed operations (see clause 4.3.6.4), where a listing of all previously encountered Context Sourcesis supplied with the request, no registration shall match if the CSourceRegistration contextSourceAlias can be found within the listing of previously encountered Context Sources.

-

Note that distributed queries (see clause 4.3.6.7), can be supplied with an EntityMap (see clause 4.5.25) which lists all Entity ids successfully matched during a previous request. If the location of an EntityMap is passed into a subsequent request, the retrieved EntityMap shall be used in preference to the matching algorithm described above, provided that the EntityMap is valid and has not expired.

-

5.13 Storing, Managing and Serving @contexts

-

5.13.1 Introduction

-

Context Brokers optionally (see clause 4.3.5) offer the capability to store and serve @contexts to clients. The stored @contexts may be managed by clients directly, via the APIs specified in clause 5.13. Clients can store custom user @contexts at the Context Broker, effectively using the Context Broker as a @context server.

-

Moreover, in order to optimize performance, brokers may automatically store and use the stored copies of common @contexts as a local cache, downloading them just once, thus avoiding fetching them over and over again at each NGSI-LD request. In order for the broker to understand if a needed @context is already in the local storage or not, the broker uses the URL, where the @context is originally hosted, as an identifier for it in the local storage. Consequently, the broker has no ability to cache @contexts that arrive to it as embedded parts within the NGSI-LD documents, since they are not uniquely (and implicitly) identified by any URL; Context Brokers only cache @contexts that are referred to by means of explicit URLs (either in the HTTP Link header or as URLs in the payload body). Thus, the recommended best-practice, in order to exploit caching, is that clients do not embed their user @contexts into their NGSI-LD documents; instead clients should explicitly host their user @contexts at their premises, or use the broker’s capability to host user @contexts on their behalf.

-

When an external @context is stored, either explicitly upon a client’s request or implicitly downloaded for caching purposes, the Context Broker generates a unique local @context identifier. The original @context’s URL, if any, is stored alongside the generated local id. The local id is then used for subsequent managing operations on the specific @context, that are specified in clauses 5.13.2 to 5.13.5. Moreover, the broker tags the entry with the current timestamp, (createdAt) so that, subsequently, clients can check the timestamp before deciding whether to force a refresh of the stored copy of the @context. This is primarily intended as a means for clients to well-behave, thus avoiding triggering continuous refresh of a stored @context on the broker, for fear that it is not at the latest version.

-

Stored @contexts are flagged as one of three kinds: “Cached”, “Hosted”, “ImplicitlyCreated”:

-
-
    -
  • Cached: @contexts implicitly and automatically fetched by the broker from external URLs during normal NGSI-LD operations are flagged as “Cached”. A locally unique identifier is generated for each @context not already in the internal storage. The downloaded content, its URL and the current time in UTC are stored alongside the locally unique identifier. Implementations shall periodically invalidate the “Cached” @contexts. Depending on the binding of the NGSI-LD API to a specific protocol, that specific protocol may provide explicit indications about expiration times of cached content. In such cases, implementations shall comply with the indications provided by the protocol. Implementations should assign a heuristic expiration time when an explicit time is not specified. Entries flagged as “Cached” shall not be served by brokers on-demand, but only be used as a local cache to improve performance.
    • -
  • Hosted: @contexts that are explicitly added by users are flagged as “Hosted”. These entries shall be served by brokers on-demand.
    • -
  • ImplicitlyCreated: @contexts that are implicitly, but ex-novo, created by the broker as a result of a user request are flagged as “ImplicitlyCreated”. For instance, when a client creates a subscription using an @context that is an array, and the broker has to notify with Content-Type “application/json”, then the broker needs this @context array to be hosted at a URL. Hence the broker has to create a new @context that is an array, and it is going to be served from an own URL. These entries shall be served by brokers on-demand.
    • -
-
-

5.13.2 Add @context

-

5.13.2.1 Description

-

With this operation, a client can ask the broker to store the full content of a specific @context, by giving it to the broker.

-

5.13.2.2 Use case diagram

-

A client can add an @context to be stored within an NGSI-LD system as shown in Figure 5.13.2.2‑1.

-
-

-
-
-

Figure 5.13.2.2-1: Add @context use case

-
-

5.13.2.3 Input data

-

A JSON object that has a top-level field named @context, i.e. a JSON object representing a JSON-LD “local context”. As specified in the JSON-LD specification [2], all extra information located outside of the @context subtree in the referenced object shall be discarded.

-

5.13.2.4 Behaviour

-

A new entry is created in the local storage and a locally unique identifier (URI) is generated for it. The JSON object representing the client-supplied @context and the current UTC time are stored alongside the locally unique identifier. That identifier shall be given back as a result in the output data. The entry is flagged as being of kind “Hosted”.

-

The behaviour described in clause 5.5.4 about JSON and JSON-LD validation shall be applied in case of invalid @context.

-

5.13.2.5 Output data

-

A locally unique URI identifying the @context in the broker’s internal storage.

-

5.13.3 List @contexts

-

5.13.3.1 Description

-

With this operation a client can obtain a list of URLs that represent all of the @contexts stored in the local context store of the broker. Each URL can be used to download the corresponding @context, and, in case the @context’s kind is “Cached”, it shall be the original URL the broker downloaded the @context from.

-

In case a details flag is set to true, the client obtains a list of JSON objects, each representing information (metadata) about an @context currently stored by the broker. Each JSON object contains information about the @context’s original URL (if any), its local identifier in the broker’s storage, its kind (“Cached”, “Hosted” and “ImplicitlyCreated”), its creation timestamp, its expiry date, and additional optional information.

-

5.13.3.2 Use case diagram

-

A client can list all @contexts stored within an NGSI-LD system as shown in Figure 5.13.3.2‑1.

-
-

-
-
-

Figure 5.13.3.2-1: List @contexts use case

-
-

5.13.3.3 Input data

-
-
    -
  • A kind filter indicating the kind of stored @contexts that are to be included in the output list. Currently, possible kinds are “Cached”, “Hosted” and “ImplicitlyCreated” (optional).
    • -
  • A boolean details flag indicating that detailed JSON objects representing metadata about the stored @contexts instead of simple URLs are requested (optional).
    • -
-
-

5.13.3.4 Behaviour

-

The broker shall provide a URL or JSON object for each @context currently stored in the internal broker’s storage, that match the filter. If no filter is specified, all kinds are included.

-

5.13.3.5 Output data

-

A list of URLs, or a list of resulting JSON objects containing the following fields:

-
-
    -
  • URL;
    • -
  • localId;
    • -
  • kind;
    • -
  • createdAt;
    • -
  • expiresAt [OPTIONAL];
    • -
  • lastUsage [OPTIONAL];
    • -
  • numberOfHits [OPTIONAL, number of times the @context was found in the storage];
    • -
  • extraInfo [OPTIONAL, used by implementations to report any kind of custom information].
    • -
-
-

5.13.4 Serve @context

-

5.13.4.1 Description

-

With this operation a client can obtain the full content of a specific @context (only for @contexts of kind “Hosted” or “ImplicitlyCreated”), which is currently stored in the broker’s internal storage, or its metadata (for all kinds of stored @contexts).

-

5.13.4.2 Use case diagram

-

A client can request the broker to serve a specific @context stored within the NGSI-LD system as shown in Figure 5.13.4.2‑1.

-
-

-
-
-

Figure 5.13.4.2-1: Serve @context use case

-
-

5.13.4.3 Input data

-
-
    -
  • The locally unique identifier that identifies the desired @context in the broker’s internal storage. Such unique identifiers are obtained by the client as a result of either a “Add @context” (clause 5.13.2) API operation or of a “List @contexts” (clause 5.13.3) API operation. For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from.
    • -
  • A boolean details flag indicating that a JSON object representing metadata about the @context, instead of the full content, is requested (optional).
    • -
-
-

5.13.4.4 Behaviour

-
-
    -
  • If details is set to false, or details is not present, the broker shall give back the full content of the @context that corresponds to the indicated local identifier, serving it from its internal storage, if the @context that corresponds to the indicated local identifier is of kind “Hosted” or “ImplicitlyGenerated”. It shall give back OperationNotSupported error if it is of kind “Cached”. It shall give back ResourceNotFound if the identifier is not found.
    • -
  • Otherwise, if details is set to true, the broker shall give back metadata about the @context that corresponds to the indicated local identifier. It shall give back ResourceNotFound error if the identifier is not found.
    • -
-
-

5.13.4.5 Output data

-

The full content of the indicated @context (or its metadata as specified in clause 5.13.3.5), or ResourceNotFound/OperationNotSupported errors.

-

5.13.5 Delete and Reload @context

-

5.13.5.1 Description

-

With this operation, a client supplies a local identifier to the broker, indicating a stored @context, that the broker shall remove from its storage. For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from. If the entry in the local storage that corresponds to the identifier is itself an array of @contexts, this operation will not delete the children, i.e. the @contexts in the array, but just the entry.

-

5.13.5.2 Use case diagram

-

A client can request the broker to delete (and optionally reload) a specific @context stored within the NGSI-LD system as shown in Figure 5.13.5.2‑1.

-
-

-
-
-

Figure 5.13.5.2-1: Delete and Reload @context use case

-
-

5.13.5.3 Input data

-
-
    -
  • The locally unique identifier that identifies the desired @context in the broker’s internal storage. For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from.
    • -
  • A reload boolean flag indicating that reloading of the @context shall be attempted (optional).
    • -
-
-

5.13.5.4 Behaviour

-
-
    -
  • If the @context identifier is not supplied, then an error of type BadRequestData shall be raised.
    • -
  • If the @context identifier does not correspond to any existing entry in the @context storage, then an error of type ResourceNotFound shall be raised.
    • -
  • If reload is true and the kind of the @context is “Cached”, implementations shall try to re-download the identified @context from its original URL, before removing it from the internal storage. If downloading fails, or the downloaded @context is invalid according to JSON and JSON-LD validation of clause 5.5.4, then an error of type LdContextNotAvailable shall be raised. More detailed information about the errors shall be specified in the ProblemDetails (see IETF RFC 7807 [10]) field of the response. In case of any error, the operation ends without removing the existing @context. Otherwise, the existing @context is replaced with the newly downloaded one.
    • -
  • If reload is true and the kind of the @context is not “Cached”, implementations shall return a BadRequestData error.
    • -
  • If reload is false (or reload is not supplied), implementations shall remove from the internal storage the @context that corresponds to the given identifier. The local identifier is used for finding the @contexts in the internal broker’s storage. If the local identifier is not in the storage, a ResourceNotFound error shall be raised.
    • -
-
-

5.13.5.5 Output data

-

None.

-

5.14 Context Source Entity Mapping

-

5.14.1 Retrieve EntityMap

-

5.14.1.1 Description

-

With this operation a client can obtain a cached EntityMap which is currently stored in the broker’s internal storage, or memory.

-

5.14.1.2 Use case diagram

-

A client can request the broker to retrieve a specific EntityMap within the NGSI-LD system as shown in Figure 5.14.1.2‑1.

-
-

-
-
-

Figure 5.14.1.2-1: Retrieve EntityMap

-
-

5.14.1.3 Input data

-

EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap).

-

5.14.1.4 Behaviour

-
-
    -
  • If the Entity ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise, return a JSON-LD object representing the EntityMap as mandated by clause 5.2.39.
    • -
-
-

5.14.1.5 Output data

-

A JSON-LD object representing the target EntityMap as mandated by clause 5.2.39.

-

5.14.2 Update EntityMap

-

5.14.2.1 Description

-

This operation allows performing a partial update on an NGSI-LD EntityMap. A partial update only changes the elements provided in the EntityMap Fragment, leaving the rest as they are.

-

5.14.2.2 Use case diagram

-

A client can request the broker to update an EntityMap which is currently stored in the broker’s internal storage as shown in Figure 5.14.2.2‑1.

-
-

-
-
-

Figure 5.14.2.2-1: Update EntityMap

-
-

5.14.2.3 Input data

-
-
    -
  • EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap).
    • -
  • A JSON-LD document representing an EntityMap.
    • -
-
-

5.14.2.4 Behaviour

-
-
    -
  • If the EntityMap ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type ResourceNotFound shall be raised.
    • -
  • Perform an update operation on the target EntityMap using the fields specified within then JSON-LD document. Any provided output-only fields shall be ignored.
    • -
-
-

5.14.2.5 Output data

-

None.

-

5.14.3 Delete EntityMap

-

5.14.3.1 Description

-

This operation allows deleting an NGSI-LD EntityMap.

-

5.14.3.2 Use case diagram

-

A client can request the broker to completely delete an EntityMap held within the NGSI-LD system as shown in Figure 5.14.3.2‑1.

-
-

-
-
-

Figure 5.14.3.2-1: Delete EntityMap

-
-

5.14.3.3 Input data

-

EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap).

-

5.14.3.4 Behaviour

-
-
    -
  • If the EntityMap ID is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint does not know about a matching EntityMap for the EntityMap ID, then an error of type ResourceNotFound shall be raised.
    • -
  • The EntityMap shall be removed from the broker’s internal storage, or memory.
    • -
-
-

5.14.3.5 Output data

-

None.

-

5.14.4 Create EntityMap for Query Entities

-

5.14.4.1 Description

-

This operation is very similar to the Query Entities operation in clause 5.7.2, except that it does not directly return Entities, but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through the included Entities.

-

5.14.4.2 Use case diagram

-

A Context Consumer can retrieve an Entity map with the Entities that match a specific query from an NGSI-LD system as shown in Figure 5.14.4.2‑1.

-
-

-
-
-

Figure 5.14.4.2-1: Query Entities for creating EntityMap use case

-
-

5.14.4.3 Input data

-
-

To simplify the operation, the same parameters as for the Query Entities operation (clause 5.7.2) are allowed, but some of these are irrelevant for creating an Entity map and thus shall be ignored.

-
-
-
    -
  • A reference to a JSON-LD @context (optional).
    • -
  • A selector of Entity types as specified by clause 4.17 (optional). Both type names (short hand string) and fully qualified type names (URI) are allowed in the selector.
    • -
  • A list (one or more) of Entity identifiers (optional).
    • -
  • A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional).
    • -
  • A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).
    • -
  • An exclusionary list member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).
    • -
  • An id pattern as a regular expression (optional).
    • -
  • An NGSI-LD query (to filter out Entities by Attribute values) as per clause 4.9 (optional).
    • -
  • An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by clause 4.10 (optional).
    • -
  • In the case of GeoJSON representation:
    • -
-
-
-
    -
  • The name of the GeoProperty attribute to use as the geometry for the GeoJSON representation as mandated by clause 4.5.16 (ignored).
    • -
  • A datasetId specifying which instance of the value is to be selected if the GeoProperty value has multiple instances as defined by clause 4.5.5 (ignored).
    • -
-
-
    -
  • -

    A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by clause 4.19 (optional).

    -
    • -
  • -

    An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties that describe them) as per clause 4.9 (optional).

    -
    • -
  • -

    A limit to the number of Entities to be retrieved. See clause 5.5.9 (ignored).

    -
    • -
  • -

    A specified language filter as per clause 4.15 (optional).

    -
    • -
  • -

    A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional).

    -
    • -
  • -

    An optional flag indicating whether to include additional Linked Entities corresponding to the Relationships retrieved and how to format those Linked Entities. See clause 4.5.23 (optional).

    -
    • -
  • -

    A limit to the depth of Linked Entities to search whilst traversing an Entity Graph. See clause 4.5.23 (optional).

    -
    • -
  • -

    A list (one or more) of Linked Entity identifiers previously encountered whilst traversing an Entity Graph. See clause 4.5.23 (optional).

    -
    • -
  • -

    A flag indicating whether to return the location of the EntityMap used within the operation (ignored, EntityMap is always returned).

    -
    • -

  • A suggested expiry time for the EntityMap (optional).

    • -
  • -

    The location of a resource holding an EntityMap of matching Entity registrations (ignored).

    -
    • -
  • -

    A datasetId parameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).

    -
    • -
  • -

    A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional).

    -
    • -
-

In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the Entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

-

5.14.4.4 Behaviour

-
-
    -
  • At least one of the following input data shall be provided:
    • -
-
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
    -
  • -

    If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses 4.9 and 4.10) an error of type BadRequestData shall be raised.

    -
    • -
  • -

    If projection attributes are present and indicate the use of Linked Entityretrieval, and the use of Linked Entityretrieval is not specified, or the projected attribute depth exceeds the Linked Entityretrieval depth, then an error of type BadRequestData shall be raised.

    -
    • -
  • -

    If the filter conditions specified by the query includes Linked Entity attributes, and the use of Linked Entityretrieval is not specified, or the Linked Entityattribute query depth exceeds the Linked Entityretrieval depth, an error of type BadRequestData shall be raised (too deep query).

    -
    • -
  • -

    If geometryProperty parameter is present and the Accept Header is not set to “application/geo+json”, then an error of type BadRequestData shall be raised.

    -
    • -
  • -

    Otherwise,

    -
    -
      -
    • -

      Term to URI expansion of type and Attribute names shall be performed, as mandated by clause 5.5.7.

      -
      • -
    • -

      If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by clause 5.5.7.

      -
      • -
    • -

      If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query that shall return an EntityMap containing the identifiers of all the Entities found locally that meet all of the following conditions:

      -
      -
      -
        -
      • id is equal to any of the id(s) passed as a parameter;
        • -
      • the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter;
        • -
      • id matches the id pattern passed as a parameter.
        • -
      -
      • -
    • -

      Otherwise, implementations shall run a query that shall return an EntityMap containing the identifiers pf all Entities found locally that meet all of the following conditions (given the respective parameter is provided):

      -
      -
      -
        -
      • id is equal to any of the id(s) passed as a parameter;
        • -
      • the Entity Type names match the selector of Entity Types (expanded) that is passed as a parameter;
        • -
      • Attribute matches any of the expanded attribute(s) in the list that is passed as a parameter;
        • -
      • id matches the id pattern passed as a parameter;
        • -
      • the filter conditions specified by the query are met (as mandated by clause 4.9);
        • -
      • the geospatial restrictions imposed by the geoquery are met (as mandated by clause 4.10); if there are multiple instances of the GeoProperty on which the geoquery is based, it is sufficient if any of these instances meets the geospatial restrictions;
        • -
      • if the Scope query is present, it shall match a present Entity Scope (as mandated by clause 4.19, for an example see annex C, clause C.5.15);
        • -
      • if the Attribute list is present, in order for an Entity to match, it shall contain at least one of the Attributes in the projection Attribute list.
        • -
      -
      • -
    • -
  • -

    Unless local scope is specified (see clause 5.5.13), for Context Source Registrations that match the query and support the “createEntityMapQueryEntity” operation (see operations and operation groups in clause 4.20), implementations shall do the following:

    -
    -
    -
      -
    • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request.
      • -
    • For each matching Context Source Registration, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an EntityMap. The mapping between the Context Source Registration and the EntityMap Id is added to the linkedMaps element of the local EntityMap and for the Entity ids included in the returned EntityMaps a mapping to the Context Source Registration is added to the entityMap element of the local EntityMap.
      • -
    -
    • -
-
-
    -
  • The local EntityMap is stored and made accessible based on its identifier.
    • -
-
-

5.14.4.5 Output data

-

The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself.

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.14.5.1 Description

-

This operation is very similar to the Query Temporal Evolution of Entities operation in clause 5.7.4, except that it does not directly return the Temporal Evolution of Entities but creates and returns an Entity map including the identifiers of the Entities that are candidates to be part of the query results. The Entity map can then be used for paginating through Temporal Evolution of the included Entities.

-

5.14.5.2 Use case diagram

-

A Context Consumer can retrieve an Entity map with the Temporal Evolution of a set of Entities which matches a specific query from an NGSI-LD system as shown in Figure 5.14.5.2‑1.

-
-

-
-
-

Figure 5.14.5.2-1: Query Temporal Evolution for creating EntityMap use case

-
-

5.14.5.3 Input data

-

To simplify the operation, the same parameters as for the Query Temporal Evolution of Entities operation (clause 5.7.4) are allowed, but some of these are irrelevant for creating an Entity map and thus will be ignored.

-
    -
  • -

    An NGSI-LD temporal query as mandated by clause 4.11.

    -
    • -
  • -

    A reference to a JSON-LD @context (optional).

    -
    • -
  • -

    A selector of Entity types as specified by clause 4.17 (optional). Both type name (short hand string) and fully qualified type name (URI) are allowed.

    -
    • -
  • -

    A restrictive list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be retrieved (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    An exclusionary list of Entity member names (“id”, “type”, “scope” or an Attribute name) to be removed (projection attributes as defined by clause 4.21) (optional).

    -
    • -
  • -

    A list (one or more) of Entity identifiers (optional).

    -
    • -
  • -

    A list (one or more) of Attribute names of which at least one shall exist in order for an Entity to be selected, and also used as query projection attributes (optional).

    -
    • -
  • -

    An id pattern as a regular expression (optional).

    -
    • -
  • -

    An NGSI-LD query (to filter out Entities by Attribute values) as per clause 4.9 (optional).

    -
    • -
  • -

    An NGSI-LD geoquery (to filter out Entities by spatial relationships) as mandated by clause 4.10 (optional).

    -
    • -
  • -

    A NGSI-LD Scope query (to filter out Entities based on their Scope) as mandated by clause 4.19 (optional).

    -
    • -
  • -

    An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties that describe them) as per clause 4.9 (optional).

    -
    • -
  • -

    A limit to the number of Entities to be retrieved. See clause 5.5.9 (ignored).

    -
    • -
  • -

    A parameter (lastN) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional).

    -
    • -
  • -

    A specified language filter as per clause 4.15 (optional).

    -
    • -
  • -

    A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional).

    -
    • -
  • -

    A flag indicating whether to return the location of the EntityMap used within the operation (ignored, EntityMap is always returned).

    -
    • -

  • A suggested expiry time for the EntityMap (optional).

    • -
  • -

    The location of a resource holding an EntityMap of matching Entity registrations (ignored).

    -
    • -
  • -

    A datasetId parameter that specifies which Attribute instances are to be selected as defined by clause 4.5.5 (optional).

    -
    • -

  • A flag indicating whether split Entities are to be expected, i.e. Entities whose information is distributed across different Context Sources (optional).

    • -
  • -

    In the general case, it is not possible to retrieve a set of entities by only specifying desired Entity identifiers, without further specifying restrictions on the entities’ types or attributes, either explicitly, via selector of Entity types or of Attribute names, or implicitly, within an NGSI-LD query or geoquery. If the execution of the operation is limited to the local scope (see clause 5.5.13), no further restrictions have to be provided.

    -
    • -
-

5.14.5.4 Behaviour

-
-
    -
  • If a temporal query is not provided then an error of type BadRequestData shall be raised.
    • -
  • At least one of the following input data shall be provided:
    • -
-
-
-
    -
  1. selector of Entity Types;
    2. -
-
-
-
    -
  1. list of Attribute names, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD Query, including at least one non-system Attribute;
    2. -
-
-
-
    -
  1. NGSI-LD GeoQuery;
    2. -
-
-
-
    -
  1. local scope (see clause 5.5.13).
    2. -
-
-
-

If none of the above is provided, then an error of type BadRequestData shall be raised (too wide query).

-
-
-
    -
  • If projection attributes or filter conditions indicate the use of Linked Entityretrieval, an error of type BadRequestData shall be raised.
    • -
  • If the list of Entity identifiers includes a URI which it is not valid, or the query, geoquery or context source filter are not syntactically valid (as per the referred clauses 4.9 and 4.10) an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of type and Attribute names shall be observed mandated by clause 5.5.7.
    • -
  • If a list of Attribute names whose values shall be expanded to URIs has been supplied, JSON-LD type coercion shall be performed as mandated by clause 5.5.7.
    • -
  • The lastN parameter refers to a number, n, of Attribute instances which shall correspond to the last n timestamps (in descending ordering) of the temporal property (by default observedAt) within the concerned temporal interval.
    • -
  • Otherwise,
    • -
-
-
    -
  • -

    Let S be the set of selected Entities i.e. the query result set.

    -
    • -
  • -

    If the split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, and local scope is not specified, implementations shall run a query so that the result set contains all the Entities found locally, that meet all of the following conditions (given the respective parameter is provided):

    -
    -
    -
      -
    • If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter.
      • -
    • If an id pattern is provided, keep in S only those Entities whose id matches the id pattern.
      • -
    • If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types.
      • -
    • From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by clause 4.11); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S4 be this new subset.
      • -
    -
    -
      -
    • -

      Otherwise implementations shall run a query that shall return the set of matching Entities (all Entities stored locally, in case only a local scope is specified); the logical steps to select the final result set of Entities, and the Attribute instances included as part of their temporal representation, are enumerated as follows:

      -
      -
      -
        -
      • If id(s) is provided, keep in S only those Entities whose id is equivalent to any of the id(s) passed as a parameter.
        • -
      • If an id pattern is provided, keep in S only those Entities whose id matches the id pattern.
        • -
      • If a selector of Entity Types is provided, keep in S only those Entities whose Entity Type names match the selector of Entity Types.
        • -
      • From S, select only those Entities any of whose Attribute instances (corresponding to the Attributes specified by the query or all if none are specified) match the temporal restrictions imposed by the temporal query (as mandated by clause 4.11); i.e. if the time series, for all the concerned Attributes of an Entity, does not include data corresponding to the temporal query interval, then such Entity shall be removed from S, thus it shall not appear in the final result set. Let S1 be this new subset.
        • -
      • If a values filter query is provided, from S1, select those Entities whose Attribute instances (during the interval defined by the temporal query) meet the matching conditions specified by the query (as mandated by clause 4.9); i.e. the values filter query shall be checked against all the Attribute instances resulting from the initial filtering performed by the temporal query. Let S2 be this new subset.
        • -
      • If no values filter query is provided, then S2 is equal to S1.
        • -
      • If geoquery is present, from S2, select those Entities whose GeoProperty instances meet the geospatial restrictions imposed by the geoquery (as mandated by clause 4.10); those geospatial restrictions shall be checked against the GeoProperty instances that are within the interval defined by the temporal query. Let S3 be this new subset.
        • -
      • If no geoquery is provided, then S3 is equal to S2.
        • -
      • If the Scope query is present, from S3, select those Entities whose Entity Scope instances match the Scope query (as mandated by clause 4.19, for an example see annex C, clause C.5.16). Let S4 be the new subset.
        • -
      • If no Scope query is provided, then S4 is equal to S3.
        • -
      -
      • -
    • -

      The local EntityMap is created based on S4.

      -
      • -
    • -
-
-
    -
  • Unless local scope is specified (see clause 5.5.13), for Context Source Registrations that match the query and support the “createEntityMapQueryTemporal” operation (see operations and operation groups in clause 4.20), implementations shall do the following:
    • -
-
-
    -

  • If split entities flag is explicitly set to true or, if not explicitly set, the default setting of the deployment allows split entities, the filters (filter conditions specified by the query, geospatial restrictions imposed by the geoquery, Scope query, Attributes) shall be removed before forwarding the request.

    • -

  • For each matching ContextSource Registration, the request is forwarded for remote querying by matching endpoints. The result of each remote query is an EntityMap. The mapping between the Context Source Registration and the EntityMap Id is added to the linkedMaps element of the local EntityMap and for the Entity ids included in the returned Entity Maps a mapping to the Context Source Registration is added to the entityMap element of the local EntityMap.

    • -
-
-
    -
  • The local EntityMap is stored and made accessible based on its identifier.
    • -
-
-

5.7.4.5 Output Data

-

The location of the local EntityMap shall be returned in a specific field in the response, as well as the EntityMap itself.

-

5.15 Context Source Identity Information

-

5.15.1 Retrieve Context Source Identity Information

-

5.15.1.1 Description

-

With this operation, a client can obtain Context Source identity information which uniquely defines the Context Source itself. In the multi-tenancy use case (see clause 4.14), a client can obtain identify information about a specific Tenant within a Context Source.

-

5.15.1.2 Use case diagram

-

A client can request the broker to retrieveidentity information about a specific Context Source within the NGSI-LD system as shown in Figure 5.15.1.2‑1.

-
-

-
-
-

Figure 5.15.1.2-1: Retrieve Context Source Identity Information

-
-

5.15.1.3 Input data

-

None.

-

5.15.1.4 Behaviour

-
-
    -
  • If the Context Source is unable to supply identity information about itself, then error of type NotImplemented shall be raised.
    • -
  • Return a JSON-LD object representing the identity of the Context Source itself as mandated by clause 5.2.40. This can also include additional configurational data dependent on the specificContext Source implementation.
    • -
-
-

5.15.1.5 Output data

-

A JSON-LD object representing the identity of the Context Source as mandated by clause 5.2.40.

-

5.16 Snapshot Functionality

-

5.16.1 Create Snapshot

-

5.16.1.1 Description

-

This operation allows creating a new snapshot.

-

5.16.1.2 Use case diagram

-

A Context Consumer can create a new snapshot to have a more consistent basis for queries on the persisted Entity information as shown in Figure 5.16.1.2‑1.

-
-

-
-
-

Figure 5.16.1.2-1: Create Snapshot use case

-
-

5.16.1.3 Input data

-
-
    -
  • A JSON-LD document conforming to the Snapshot data type as mandated by clause 5.2.41.
    • -
-
-

5.16.1.4 Behaviour

-
-
    -
  • If the data types, cardinalities and restrictions expressed by clause 5.2.41 are not met, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD endpoint already knows about this Snapshot, as there is an existing Snapshot whose id (URI) is equivalent, an error of type AlreadyExists shall be raised.
    • -
  • If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation.
    • -
  • The createdAt and modifiedAt timestamps are set to the current time of the NGSI-LD system.
    • -
  • The snapshotStatus member is set to preparation.
    • -
  • The expiresAt member shall be set, taking into account the snapshotLifetime requested, but applying the configured limit of the NGSI-LD system.
    • -
  • If the Snapshot document does not include a snapshotPriority, the snapshotPriority shall be set to 5.
    • -
  • The request returns, confirming the creation of the snapshot to the requesting Context Consumer, providing the Snapshot identifier. The status is accessible to the Context Consumer as described in Clause 5.16.3. The following is executed in the background.
    • -
  • Implementations shall execute the Queries specified in the snapshotQueries member, in each case following the behaviour described in clause 5.7.2.4. If the size of the respective results require pagination, all pages are to be retrieved completely. The response details for each query execution (aggregated across paginated ones) shall be stored in the snapshotQueryDetails list, at the same position as the query in snapshotQueries.
    • -
  • Implementations shall execute the Temporal Queries specified in the snapshotTemporalQueries member, in each case following the behaviour described in clause 5.7.4.4. If the size of the respective results require pagination, all pages are to be retrieved completely. The response details for each query execution (aggregated across paginated ones) shall be stored in the snapshotTemporalQueryDetails list, at the same position as the query in snapshotTemporalQueries.
    • -
  • The retrieved Entity information shall be stored by the NGSI-LD system, so that local NGSI-LD operations can then be executed on it.
    • -
  • After all information has been stored, the snapshotStatus member is set to success, if all queries and temporal queries were executed successfully and yielded at least one result, to partial, if at least one query or temporal query was executed successfully and yielded a result, to empty, if at least one query or temporal query was executed successfully, but without yielding a result, and to failure otherwise.
    • -
  • If the endpoint member is present, a Snapshot notification is sent as described in Clause 5.16.6.
    • -
-
-

5.16.1.5 Output data

-

A URI identifying the newly created Snapshot.

-

5.16.2 Clone Snapshot

-

5.16.2.1 Description

-

This operation allows cloning a snapshot stored in an NGSI-LD system.

-

5.16.2.2 Use case diagram

-

A Context Consumer can clone an existing snapshot stored in an NGSI-LD system as shown in Figure 5.16.2.2‑1.

-
-

-
-
-

Figure 5.16.2.2-1: Clone Snapshot use case

-
-

5.16.2.3 Input data

-
-
    -
  • A URI identifying the Snapshot to be cloned.
    • -
  • A JSON-LD document conforming to the Snapshot data type as mandated by clause 5.2.41, but without snapshotQueriesDetails and snapshotQueriesTemporalDetails elements.
    • -
-
-

5.16.2.4 Behaviour

-
-
    -
  • If the data types, cardinalities and restrictions expressed by clause 5.2.41 are not met, then an error of type BadRequestData shall be raised.
    • -
  • If the identifier of the Snapshot to be cloned is not found, an error of type ResourceNotFound shall be raised.
    • -
  • If the Snapshot document includes a Snapshot identifier and there is an existing Snapshot whose id (URI) is equivalent, an error of type AlreadyExists shall be raised.
    • -
  • If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation.
    • -
  • The createdAt and modifiedAt timestamps of the clone are set to the current time of the NGSI-LD system.
    • -
  • The snapshotStatus member of the clone is set to preparation.
    • -
  • The expiresAt member shall be set, taking into account the snapshotLifetime requested, but applying the configured limit of the NGSI-LD system.
    • -
  • The request returns, confirming the creation of the cloned Snapshot to the requesting Context Consumer. The status is accessible to the Context Consumer as described in Clause 5.16.3. The following is executed in the background.
    • -
  • All Entity and Temporal Evolution of Entity data that is part of the Snapshot to be cloned is copied to the clone Snapshot.
    • -
  • After all information has been stored, the snapshotStatus member is set to success, if cloning was successful, and to failure otherwise.
    • -
  • If the endpoint member is present, a Snapshot notification is sent as described in Clause 5.16.6.
    • -
-
-

5.16.2.5 Output data

-

A URI identifying the newly created Snapshot.

-

5.16.3 Retrieve Snapshot Status

-

5.16.3.1 Description

-

This operation allows retrieving the status of a Snapshot stored in an NGSI-LD system.

-

5.16.3.2 Use case diagram

-

A Context Consumer can retrieve a the status of a Snapshot from an NGSI-LD system as shown in Figure 5.16.3.2‑1.

-
-

-
-
-

Figure 5.16.3.2-1: Retrieve Snapshot Status use case

-
-

5.16.3.3 Input data

-

Snapshot Id (URI) of the Snapshot whose status is to be retrieved.

-

5.16.3.4 Behaviour

-
-
    -
  • If the Snapshot Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the identifier provided does not correspond to any existing Snapshot in the system, then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwise, implementations shall retrieve the Snapshot status and return it to the caller.
    • -
-
-

5.16.3.5 Output data

-

A JSON-LD object representing the Snapshot status as mandated by clause 5.2.41.

-

5.16.4 Update Snapshot Status

-

5.16.4.1 Description

-

This operation allows updating an existing Snapshot.

-

5.16.4.2 Use case diagram

-

A Context Consumer can update an existing Snapshot within an NGSI-LD system as shown in Figure 5.16.4.2‑1.

-
-

-
-
-

Figure 5.16.4.2-1: Update Snapshot Status use case

-
-

5.16.4.3 Input data

-
-
    -
  • Snapshot identifier (URI), the target Snapshot.
    • -
  • A JSON-LD document representing a Snapshot Fragment
    • -
-
-

5.16.4.4 Behaviour

-
-
    -
  • If the Snapshot id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the NGSI-LD System does not know about the target Snapshot, because there is no existing Snapshot whose id (URI) is equivalent, an error of type ResourceNotFound shall be raised.
    • -
  • Execute the behaviour defined in clause 5.5.4 on JSON-LD validation.
    • -
  • If the data types and restrictions expressed by clause 5.2.41 are not met by the Snapshot Fragment – in particular whether elements can be updated – then an error of type BadRequestData shall be raised.
    • -
  • Term to URI expansion of Attribute names shall be observed as mandated by clause 5.5.7.
    • -
  • Then, implementations shall modify the target Snapshot as mandated by clause 5.5.8.
    • -
-
-

5.16.4.5 Output data

-

A JSON-LD object representing the Snapshot status as mandated by clause 5.2.41.5.16.5 Delete Snapshot

-

5.16.5.1 Description

-

This operation allows deleting an existing Snapshot.

-

5.16.5.2 Use case diagram

-

A Context Consumer can delete a Snapshot within an NGSI-LD system as shown in Figure 5.16.5.2‑1.

-
-

-
-
-

Figure 5.16.5.2-1: Delete Snapshot use case

-
-

5.16.5.3 Input data

-
-
    -
  • A Snapshot identifier (URI), the target Snapshot.
    • -
-
-

5.16.5.4 Behaviour

-
-
    -
  • If the Snaptshot Id is not present or it is not a valid URI, then an error of type BadRequestData shall be raised.
    • -
  • If the Snapshot id provided does not correspond to any existing Snapshot in the system, then an error of type ResourceNotFound shall be raised.
    • -
  • Otherwisem implementations shall delete the Snapshot.
    • -
-
-

5.16.5.5 Output data

-

None.

-

5.16.6 Snapshot status notification behaviour

-

A Snapshot status notification allows the subscriber, typically the creator of the Snapshot, to be notified when the Snapshot is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour:

-
-
    -
  • SnaptshotNotification (clause 5.3.4) messages can only be sent, if the endpoint member is set.
    • -
  • SnaptshotNotification messages are sent to the URI specified in the endpoint member of the Snapshot status.
    • -
  • The information in the recevierInfo member of the Snapshot status shall be added to the SnapshotNotification message in the way required for the binding protocol.
    • -
  • Snapshot Status Notifications shall be sent after all the specified Snapshot queries have been executed, the query results have been integrated and the Snapshot status has been updated accordingly.
    • -
  • Snapshot status Notifications shall also be sent after any Snapshot status update, e.g. informing about the actual updated expiresAt timestamp.
    • -
  • The SnapshotNotification shall be as mandated by clause 5.3.4.
    • -
-
-

5.16.7 Purge Snapshots

-

5.16.7.1 Description

-

This operation allows purging selected Snapshots.

-

5.16.7.2 Use case diagram

-

A Context Consumer can purge Snapshots within an NGSI-LD system as shown in Figure 5.16.7.2‑1.

-
-

-
-
-

Figure 5.16.7.2-1: Purge Snapshots use case

-
-

5.16.7.3 Input data

-
-
    -
  • An NGSI-LD Query to select fitting Snapshots to be purged based on members of the Snapshot data type (see Table 5.2.41‑1), as per clause 4.9.
    • -
-
-

5.16.7.4 Behaviour

-
-
    -
  • If the NGSI-LD Query is not present or it is not a valid as per clause 4.9, restricted to members of the Snapshot data type, then an error of type BadRequestData shall be raised.
    • -
  • Implementations shall purge the Snapshots fitting the NGSI-LD Query.
    • -
-
-

5.16.7.5 Output data

-

None.

-
- - - - - diff --git a/API/11-tabapi-http-binding.html b/API/11-tabapi-http-binding.html deleted file mode 100644 index 9d30727e8b46f546dba0a52702b28b61b83c0a19..0000000000000000000000000000000000000000 --- a/API/11-tabapi-http-binding.html +++ /dev/null @@ -1,14364 +0,0 @@ - - - - - - - -6 API HTTP Binding - - - - - - - - - - - - -
-

6 API HTTP Binding

-

6.1 Introduction

-

This clause defines the resources and operations of the NGSI-LD API. The NGSI-LD API is structured in terms of HTTP [3], [4] verbs, request and response payload bodies.

-

A non-normative OAS specification [i.12] of the referred HTTP binding can be found at [i.14].

-

6.2 Global Definitions and Resource Structure

-

All resource URIs of this API shall have the following root:

-
-
    -
  • {apiRoot}/{apiName}/{apiVersion}/
    • -
-
-
-
-

NOTE 1:

-
-
-

The apiRoot discovery process is out of the scope of the present document.

-
-
-
-
-

NOTE 2:

-
-
-

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different, e.g. the Context Source related aspects can be implemented by a Context Registry as shown for the distributed and federated architectures (see clause 4.3 ), whereas the Entity-related aspects would be implemented by a Context Broker .

-
-
-
-
-

NOTE 3:

-
-
-

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different than the apiRoot for temporal aspects, e.g. the temporal aspects can be implemented by an NGSI-LD subsystem specialized in historical data.

-
-
-

The apiRoot includes the scheme (“http” or “https”), host and optional port, and an optional prefix string. The API shall support HTTP over TLS (also known as HTTPS - see IETF RFC 2818 [18]). TLS version 1.2 as defined by IETF RFC 5246 [19] shall be supported. HTTP without TLS is not recommended.

-

The apiName shall be set to “ngsi-ld” and the apiVersion shall be set to “v1” for the present document.

-

All resource URIs are defined relative to the above root URI. The structure of the resources under the root URI is shown in Figure 6.2‑1 and methods defined on them are shown in Table 6.2‑1.

-

An OpenAPI companion specification is available, see [37].

-
-

-
-
-

Figure 6.2-1: Resource URI structure of the NGSI-LD API

-
-
-

Table 6.2-1: Resources and HTTP methods defined on them

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Resource Name -
-Resource URI -
-HTTP Method -
-Meaning -
-Clauses -
-Entity List -
-/entities/ -
-POST -
-

Entity creation

-
-5.6.1; 6.4.3.1 -
-GET -
-

Query entities

-
-5.7.2; 6.4.3.2 -
-DELETE -
-

Purge entities

-
-5.6.21; 6.4.3.3 -
-Entity by id -
-/entities/{entityId} -
-GET -
-

Entity retrieval by id

-
-5.7.1; 6.5.3.1 -
-DELETE -
-

Entity deletion by id

-
-5.6.6; 6.5.3.2 -
-PATCH -
-

Entity merge by id

-
-5.6.17; 6.5.3.4 -
-PUT -
-

Entity replacement by id

-
-5.6.18; 6.5.3.3 -
-Attribute List -
-/entities/{entityId}/attrs/ -
-POST -
-

Append Attributes to Entity

-
-5.6.3; 6.6.3.1 -
-PATCH -
-

Update Attributes of an Entity

-
-5.6.2; 6.6.3.2 -
-Attribute by id -
-/entities/{entityId}/attrs/{attrId} -
-PATCH -
-

Partial Attribute update

-
-5.6.4; 6.7.3.1 -
-DELETE -
-

Attribute deletion

-
-5.6.5; 6.7.3.2 -
-PUT -
-

Attribute replacement

-
-5.6.19; 6.7.3.3 -
-Subscriptions List -
-/subscriptions/ -
-POST -
-

Create Subscription

-
-5.8.1; 6.10.3.1 -
-GET -
-

Retrieve list of Subscriptions

-
-5.8.4; 6.10.3.2 -
-Subscription by Id -
-/subscriptions/{subscriptionId} -
-GET -
-

Subscription retrieval by id

-
-5.8.3; 6.11.3.1 -
-PATCH -
-

Subscription update by id

-
-5.8.2; 6.11.3.2 -
-DELETE -
-

Subscription deletion by id

-
-5.8.5; 6.11.3.3 -
-Entity Types -
-/types/ -
-GET -
-

Retrieve available entity types

-
-5.7.5 and 5.7.6; 6.25.3.1 -
-Entity Type -
-/types/{type} -
-GET -
-

Details about available entity type

-
-5.7.7; 6.26.3.1 -
-Attributes -
-/attributes/ -
-GET -
-

Available attributes

-
-5.7.8 and 5.7.9; 6.27.3.1 -
-Attribute -
-/attributes/{attrId} -
-GET -
-

Details about available attribute

-
-5.7.10; 6.28.3.1 -
-Context source registration list -
-/csourceRegistrations/ -
-POST -
-

Csource registration creation

-
-5.9.2; 6.8.3.1 -
-GET -
-

Discover Csource registrations

-
-5.10.2; 6.8.3.2 -
-Context source registration by Id -
-/csourceRegistrations/{registrationId} -
-GET -
-

Csource registration retrieval by id

-
-5.10.1; 6.9.3.1 -
-PATCH -
-

Csource registration update by id

-
-5.9.3; 6.9.3.2 -
-DELETE -
-

Csource registration deletion by id

-
-5.9.4; 6.9.3.3 -
-Context source registration subscription list -
-/csourceSubscriptions/ -
-POST -
-

Create subscription to Csource registration

-
-5.11.2; 6.12.3.1 -
-GET -
-

Retrieval of list of subscription to Csource registration

-
-5.11.5; 6.12.3.2 -
-Context source registration subscription by Id -
-/csourceSubscriptions/{subscriptionId} -
-GET -
-

Csource registration subscription retrieval by id

-
-5.11.4; 6.13.3.1 -
-PATCH -
-

Csource registration subscription update by id

-
-5.11.3; 6.13.3.2 -
-DELETE -
-

Csource registration subscription deletion by id

-
-5.11.6; 6.13.3.3 -
-Entity Operations. Create -
-/entityOperations/create -
-POST -
-

Batch Entity creation

-
-5.6.7; 6.14.3.1 -
-Entity Operations. Upsert -
-/entityOperations/upsert -
-POST -
-

Batch Entity creation or update (upsert)

-
-5.6.8; 6.15.3.1 -
-Entity Operations. Update -
-/entityOperations/update -
-POST -
-

Batch Entity update

-
-5.6.9; 6.16.3.1 -
-Entity Operations. Delete -
-/entityOperations/delete -
-POST -
-

Batch Entity deletion

-
-5.6.10; 6.17.3.1 -
-Entity Operations. Query -
-/entityOperations/query -
-POST -
-

Query entities based on POST

-
-5.7.2; 6.23.3.1 -
-

Entity Operations.

-

Merge

-
-/entityOperations/merge -
-POST -
-

Batch Entity merge

-
-5.6.20; 6.31.3.1 -
-Temporal Evolution of Entities -
-/temporal/entities/ -
-POST -
-

Temporal Evolution of an Entity creation

-
-5.6.11; 6.18.3.1 -
-GET -
-

Query Temporal Evolution of Entities

-
-5.7.4; 6.18.3.2 -
-Temporal Evolution of an Entity by id -
-/temporal/entities/{entityId} -
-GET -
-

Temporal Evolution of an Entity retrieval by id

-
-5.7.3; 6.19.3.1 -
-DELETE -
-

Temporal Evolution of an Entity deletion by id

-
-5.6.16; 6.18.3.2 -
-Temporal Representation of Attribute List -
-/temporal/entities/{entityId}/attrs/ -
-POST -
-

Temporal Evolution of Attribute of an Entity instance addition

-
-5.6.12; 6.20.3.1 -
-Temporal Representation of Attribute by id -
-/temporal/entities/{entityId}/attrs/{attrId} -
-DELETE -
-

Attribute from Temporal Evolution of an Entity deletion

-
-5.6.13; 6.21.3.1 -
-Temporal Representation of Attribute Instance by id -
-/temporal/entities/{entityId}/attrs/{attrId} /{instanceId} -
-PATCH -
-

Attribute Instance from Temporal Evolution of an Entity update by instance id

-
-5.6.14; 6.22.3.1 -
-DELETE -
-

Attribute Instance from Temporal Evolution of an Entity deletion by instance id

-
-5.6.15; 6.22.3.2 -
-Create EntityMap for Query Temporal Evolution of Entities -
-/temporal/entityMaps/ -
-GET -
-

Query temporal evolution of entities for creating entity map

-
-

5.15.4;

-

6.35.3.1

-
-POST -
-

Query temporal evolution of entities for creating entity map based on POST

-
-

5.15.4;

-

6.35.3.2

-
-Temporal Query Operation -
-/temporal/entityOperations/query -
-POST -
-

Query Temporal Evolution of Entities based on POST

-
-5.7.4; 6.24.3.1 -
-Add and List @context -
-/jsonldContexts -
-POST -
-

Add a user @context to the internal cache

-
-5.13.2; 6.29.3.1 -
-GET -
-

List all cached @contexts

-
-5.13.3; 6.29.3.2 -
-Serve, Delete and Reload @context -
-/jsonldContexts/{contextId} -
-GET -
-

Serve one specific user @context

-
-5.13.4; 6.30.3.1 -
-DELETE -
-

Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it

-
-5.13.5; 6.30.3.2 -
-Create EntityMap for Query Entities -
-/entityMaps/ -
-GET -
-

Query entities for creating entity map

-
-

5.14.4;

-

6.34.3.1

-
-POST -
-

Query entities for creating entity map based on POST

-
-

5.14.4;

-

6.34.3.2

-
-Retrieve, Update and Delete Entity Maps -
-/entityMaps/{entityMapId} -
-GET -
-

EntityMap Retrieval by id

-
-5.14.1; 6.32.3.1 -
-PATCH -
-

EntityMap Update by id

-
-5.14.2; 6.32.3.2 -
-DELETE -
-

EntityMap Deletion by id

-
-5.14.3; 6.32.3.3 -
-Retrieve Context Source Identity Information -
-/info/sourceIdentity -
-GET -
-

Context Source Identity Retrieval

-
-5.15.1; 6.33.3.1 -
-Create Snapshot or Purge Snapshots -
-/snapshots/ -
-POST -
-

Create Snapshot

-
-

5.16.1;

-

6.36.3.1

-
-DELETE -
-

Purge Snapshots

-
-

5.16.7;

-

6.36.3.2

-
-Retrieve and Update Snapshot Status or Delete Snapshot -
-/snapshots/{snapshotId} -
-GET -
-

Retrieve Snapshot Status

-
-

5.16.3;

-

6.37.3.1

-
-PATCH -
-

Update Snapshot Status

-
-

5.16.4;

-

6.37.3.2

-
-DELETE -
-

Delete Snapshot

-
-

5.16.5;

-

6.37.3.3

-
-Clone Snapshot -
-/snapshots/{snapshotId}/clone -
-POST -
-

Clone Snapshot

-
-

5.16.2;

-

6.38.3.1

-
-

6.3 Common Behaviours

-

6.3.1 Introduction

-

This clause extends the API common behaviours to the particularities of the HTTP REST binding. For each operation implementations shall exhibit the common behaviours as specified by clause 5.5 and the behaviours defined by the present clause.

-

6.3.2 Error Types

-

This clause associates API error types (which shall be contained in the response payload body) defined by clause 5.5.2 with HTTP status codes as shown in Table 6.3.2‑1.

-
-

Table 6.3.2-1: Mapping of error types to HTTP status codes

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Error Type -
-HTTP status -
-https://uri.etsi.org/ngsi-ld/errors/AlreadyExists -
-

409

-
-https://uri.etsi.org/ngsi-ld/errors/BadRequestData -
-

400

-
-https://uri.etsi.org/ngsi-ld/errors/InternalError -
-

500

-
-https://uri.etsi.org/ngsi-ld/errors/InvalidRequest -
-

400

-
-https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable -
-

504

-
-https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport -
-

501

-
-https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant -
-

404

-
-https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported -
-

422

-
-https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound -
-

404

-
-https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery -
-

403

-
-https://uri.etsi.org/ngsi-ld/errors/TooManyResults -
-

403

-
-

In addition, implementations shall support the standard specific errors of HTTP bindings, such as the following:

-
-
    -
  • “Method Not Allowed” (405) which shall be raised when a client invokes a wrong HTTP verb over a resource. Implementations shall provide the allowed HTTP methods as mandated by IETF RFC 7231 [3] in section 6.5.5.
    • -
  • “Request Entity too large” (413) which shall be raised when the HTTP input data stream provided by a client was too large i.e. too many bytes.
    • -
  • “Length required” (411) which shall be raised when an HTTP request provided by a client does not define the “Content-Length” HTTP header.
    • -
  • “Unsupported Media Type” (415) which shall be raised when an HTTP request payload body (as per the “Content-Type” header) it is not “application/json” nor “application/ld+json”.
    • -
  • “Not Acceptable” 406) which shall be raised when the response media types that are acceptable by a client (as per the”Accept” header) do not include or expand to “application/json” nor “application/ld+json”.
    • -
-
-

6.3.3 Reporting errors

-

When an API operation results in an error, implementations shall return an HTTP response as follows:

-
-
    -
  • Content-Type: application/json.
    • -
  • HTTP Status Code: As per clause 6.3.2 depending on error type.
    • -
  • Payload body: A JSON object including all the terms defined by clause 5.5.3.
    • -
-
-

6.3.4 HTTP request preconditions

-

For HTTP POST, PATCH and PUT HTTP requests implementations shall check the following preconditions:

-
-
    -
  • Content-Type header shall be “application/json” or “application/ld+json”.
    • -
  • Content-Length header shall include the length of the request payload body.
    • -
-
-

For HTTP PATCH requests “application/merge-patch+json” is allowed as Content-Type, as mandated by IETF RFC 7396 [16]. Implementations shall interpret such MIME type as equivalent to “application/json”.

-

For HTTP GET requests and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall check the following preconditions:

-
-
    -
  • Accept header shall include (or define a media range that can be expanded to) at least one of:
    • -
-
-
-
    -
  • “application/json”
    • -
  • “application/ld+json”
    • -
  • “application/geo+json”
    • -
-
-

The order of the list above is significant. If the Accept header can be expanded to more than one of the options of the list, the first one of the list shall be selected, unless amended by the HTTP Accept header processing rules, e.g. the presence of a “q” parameter indicating a relative weight, (as mandated by IETF RFC 7231 [3], section 5.3.2) require otherwise.

-

If the Accept header is not present, “application/json” shall be assumed.

-

If an incoming HTTP request does not meet the preconditions stated above, an HTTP error response of type InvalidRequest shall be returned, with the following exceptions:

-
-
    -
  • “Content-Length” HTTP header absence, shall result in just a 411 HTTP status code (without any payload body).
    • -
  • Unsupported Media Type, i.e. “Content-Type” header is not “application/json” nor “application/ld+json”, shall result in just a 415 HTTP status code (without any payload body).
    • -
  • Not Acceptable Media Type, i.e. “Accept” header does not imply “application/json” nor “application/ld+json”, shall result in a 406 HTTP status code and the body of the message shall contain the list of the available representations of the resources.
    • -
-
-

Notwithstanding the above, if the Accept Header is set to “application/geo+json”:

-
-
    -
  • For Context Information Consumption operations only, specifically “Retrieve Entity” (see clause 5.7.1) and “Query Entity” (clause 5.7.2) GeoJSON is considered as an acceptable content type and a GeoJSON payload will be returned.
    • -
  • For all other operations, the request will result in a Not Acceptable Media Type error, returning a 406 HTTP status code and the body of the message shall contain the list of the available representations of the resources.
    • -
-
-

6.3.5 JSON-LD @context resolution

-

In the HTTP REST binding, implementations shall resolve the JSON-LD @*context* associated to an incoming HTTP request as follows:

-
-
    -
  • If the request verb is GET or DELETE, then the associated JSON-LD @context shall be obtained from a Link header [7] as mandated by JSON-LD [2], section 6.2. In the absence of such Link header, then the associated @context shall be the default JSON-LD @context.
    • -
-
-
-
-

EXAMPLE:

-
-
-

The structure of the referred Link header is shown below. The first component (between < > ) is a dereferenceable URI pointing to the JSON-LD document which contains the @context to be used to expand the terms used by the corresponding operation. The second parameter is a fixed, non-dereferenceable URI used to denote a unique identifier and semantics for this header (marking it as a link to a JSON-LD @context ). The third and final parameter flags the MIME type of the linked resource (JSON-LD).

-
-
-
-
    -
  • If the request verb is POST, PATCH or PUT and the Content-Type header is “application/json”, then the @context shall be obtained from a Link Header as mandated by JSON-LD [2], section 6.2. In the absence of such Link Header, then the @context shall be the default @context. In any case, if the request payload body (as JSON) contains a @context term, then an HTTP error response of type BadRequestData shall be raised.
    • -
  • If the request verb is POST, PATCH or PUT and the Content-Type header is “application/ld+json”, then the associated @context shall be obtained from the request payload body itself. If no @context can be obtained from the request payload body, then an HTTP error response of type BadRequestData shall be raised. In any case, the presence of a JSON-LD Link header in the incoming HTTP request when the Content-Type header is “application/ld+json” shall result in an HTTP error response of type BadRequestData.
    • -
-
-

In summary, from a developer’s perspective, for POST, PATCH and PUT operations, if MIME type is “application/ld+json”, then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is “application/json”, then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

-

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

-

6.3.6 HTTP response common requirements

-

Implementations shall honour the Accept header provided by HTTP requests as mandated by clause 6.3.4:

-
-
    -
  • If the target response’s MIME type is “application/json” such response shall include a Link to the associated JSON-LD @context as mandated by [2], section 6.2.
    • -
-
-
-
    -
  • If the Prefer header [26] is set to “ngsi-ld=<version>” then implementations shall set the Preference-Applied header to “ngsi-ld=<conformant-version>” in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in clause 4.3.6.8.
    • -
-
-
-
    -
  • If the target response’s MIME type is “application/ld+json”, then the response payload body provided by the HTTP response shall include a JSON-LD @context.
    • -
-
-
-
    -
  • If the Prefer Header [26] is set to “ngsi-ld=<version>” then implementations shall set Preference-Applied header to “ngsi-ld=<conformant-version>” in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in clause 4.3.6.8.
    • -
-
-
-
    -
  • If the target response’s MIME type is “application/geo+json” and the Prefer Header [26] is omitted or set to “body=ld+json”, then the response payload body provided by the HTTP response shall include a JSON-LD @context, and the representation of the entities shall be in GeoJSON format in the response payload body.
    • -
  • If the target response’s MIME type is “application/geo+json” and the Prefer Header [26] is set to “body=json” such response shall include a Link to the associated JSON-LD @context as mandated by [2], section 6.2 and the representation of the entities shall be in GeoJSON format in the response payload body, and @context shall be omitted from the payload body.
    • -
-
-

Operations where the response payload body is not present such as successful HTTP POST, PATCH, PUT or DELETE operations and all error responses, do not include the Link header in the response.

-

Operations that result in an error that return a payload or that result in a partial success (207 Multi-Status) shall always respond with MIME type “application/json”, regardless of the Accept header. It is assumed that if a client application understands any of the supported MIME types, the application shall understand “application/json” errors. Only Fully Qualified Names shall be used in the payload body of error or partial success responses, as there is no context present.

-

No Content-Length HTTP header shall be present if the response code is 204.

-

6.3.7 Representation of Entities

-

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), Context Broker implementations shall support the parameter specified in Table 6.3.7‑1, which specifies all possible supported representations formats.

-

In contrast, at a minimum, registered Context Source implementations shall support the normalized representation of Entities as default. When a registered Context Source is unable to support additional representations, a 501 Not Implemented Error shall be raised.

-
-

Table 6.3.7-1: Entity representations: format + options parameter

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

When its value is “normalized”, a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2.

-

When its value is “concise”, a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members.

-

When its value is “simplified” (or its synonym “keyValues”). a simplified representation of Entities shall be provided as defined by clause 4.5.4

-

If the Accept Header is set to “application/geo+json” the response will be in simplified GeoJSON format as defined by clause 4.5.17.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword “normalized”, a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2.

-

When its value includes the keyword “concise”, a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members.

-

When its value includes the keyword “simplified” (or its synonym “keyValues”). a simplified representation of Entities shall be provided as defined by clause 4.5.4.

-

If the Accept Header is set to “application/geo+json” the response will be in simplified GeoJSON format as defined by clause 4.5.17.

-
-

6.3.8 Notification behaviour

-

In the HTTP binding a notification that is triggered by a subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the subscription structure (defined by clauses 5.2.12, 5.2.14 and 5.2.15). For the HTTP binding, the protocol part of the endpoint URI is http or https. In case the optional MQTT notification binding (clause 7) is supported, the protocol part of the endpoint URI can also be mqtt or mqtts. The MIME type associated to the POST request shall be “application/json” by default. However, this can be changed to “application/ld+json”, or “application/geo+json” by means of the endpoint.accept member.

-

If the target MIME type is “application/json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP header for each member named “key” of the key, value pairs that make up the array shall be generated and included in the HTTP POST’s list of headers. The content of each custom header shall be set equal to the content of the corresponding “value” member of the KeyValuePair. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

If the target MIME type is “application/geo+json” and the notification.endpoint.receiverInfo member contains a key “Prefer”whose value is set to “body=json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the target MIME type is “application/geo+json” and the notification.endpoint.receiverInfo contains a key “Prefer” whose value is set to “body=ld+json” or the “Prefer” key is omitted or notification.endpoint.receiverInfo does not exist, then the HTTP notification request includes an @context element in the payload body.

-

6.3.9 Csource Notification behaviour

-

In the HTTP binding a csource notification that is triggered by a csource subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the csource subscription structure (defined by clauses 5.2.12 and 5.2.14). The MIME type associated to the POST request shall be “application/json” by default. However, this can be changed to “application/ld+json” by means of the endpoint.accept member.

-

If the target MIME type is “application/json” then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP Header for each member named “key” of the key, value pairs that make up the array shall be generated and included in the HTTP POST’s list of headers. The content of each custom header shall be set equal the content of the corresponding “value” member of the KeyValuePair. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

6.3.10 Pagination behaviour

-

For HTTP operations corresponding to the operations listed in clause 4.12 (see Table 6.2‑1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.3.10‑1.

-
-

Table 6.3.10-1: Pagination: limit parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Integer -
-0..1 -
-

Only values greater or equal to 0.

-

It defines the limit to the number of NGSI-LD Elements that shall be retrieved at a maximum as mandated by clause 5.5.9. The value 0 is only allowed in combination with the count URI parameter.

-
-

This clause defines the specific HTTP binding mechanisms that shall be used in conjunction with the behaviours defined by clause 5.5.9. Particularly, to flag the existence of related pages that could be retrieved when dealing with query operations involving pagination, NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header field as mandated by IETF RFC 8288 [7], clause 3, as follows:

-
-
    -
  • The pointers to the next and previous pages (when needed as mandated by clause 5.5.9) shall be serialized as link-value elements. The content of such link-value(s) shall be:
    • -
-
-
-
    -
  • For the next page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the next page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to “next”, registered under the IANA Registry of Link Relation Types [20].
    • -
  • For the previous page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the previous page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to “prev”, registered under the IANA Registry of Link Relation Types [20].
    • -
-
-
-
    -
  • At least, the “type” Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [7], , and its value shall be exactly equal to the media type resulting from the original request made by the NGSI-LD Client (the request that triggered the current pagination iteration).
    • -
-
-
-
-

EXAMPLE:

-
-
-

If the media type requested originally was “application/json” then during the entire pagination iteration the value of the Link Target Attribute “type” shall be “application/json”.

-
-
-

If the transparent pagination option as described in clause 5.5.9.2 is used, the URI-references for the “next” and“prev” link to the next and previous pages respectively should include the limit parameter as specified in Table 6.3.10‑1 and the offset parameter as specified in Table 6.3.10‑2, giving the Context Consumer more control, i.e. to adapt the size of the page using limit and jump to a desired set of elements in the results using offset.

-
-

Table 6.3.10-2: Pagination: offset parameter

-
- ------ - - - - - - - - - - - - - - - - -

{ondemand_PAR_alignment_CENTER}

-

Name

{ondemand_PAR_alignment_CENTER}

-

Data Type

{ondemand_PAR_alignment_CENTER}

-

Cardinality

{ondemand_PAR_alignment_CENTER}

-

Remarks

offsetInteger0..1

Only values greater or equal to 0.

-

It defines the offset of the first NGSI-LD Element that shall be retrieved from the beginning of the result set. If offset is set to a value larger than the result set, the offset should be assumed to be equal to the size of the result set, i.e. only the last element of the result set is to be returned if there are any results.

-

Temporal representation of resources adds an additional dimension to the pagination. Depending on the requested time range, the response will contain multiple instances of the requested Attribute, and therefore an additional pagination mechanism for those temporal representations is required, in order to limit the time range of the response. If no limits are specified, a default limit is enforced, depending on implementation specific configurations. For HTTP operations on Temporal Evolutionof Entities, implementations shall use the Partial Content Response (206) as specified by IETF RFC 7233 [31], clause 4.1, if the implementation is not able to respond with the full representation at once. In this case, for requests where the parameter lastN is present, pagination shall happen “backwards” (from the most recent to the least recent timestamp in the requested time range). For requests without the parameter lastN, pagination shall happen “forwards” (from the least recent to the most recent timestamp in the requested time range).

-

This is achieved by including the “Content-Range” header field with the following contents:

-
-
    -
  • “unit” shall be equal to “DateTime”;
    • -
  • “range-start” and “range-end” shall be of type DateTime. They depend on the requested time relationship timerel (as defined by clause 4.11), as follows:
    • -
-
-
-
    -
  • If the lastN parameter is present, pagination shall happen “backwards”:
    • -
-
-
-
    -
  • “range-start” shall be equal to “timeAt” for requests with timerel=before, “endTimeAt” for requests with timerel=between, or the most recent timestamp in the range of the response, for requests with timerel=after;
    • -
  • “range-end” shall be equal to the least recent timestamp in the range of the response;
    • -
  • “size” shall be equal to the requested lastN.
    • -
-
-
-
    -
  • If the lastN parameter is not present, pagination shall happen “forwards”:
    • -
-
-
-
    -
  • “range-start” shall be equal to timeAt for requests with timerel=after or timerel=between, or the least recent timestamp in the range of the response, for requests with timerel=before;
    • -
  • “range-end” shall be equal to the most recent timestamp in the range of the response;
    • -
  • “size” shall be equal to “*”.
    • -
-
-

6.3.11 Including system Attributes

-

For HTTP GET operations performed over the resources /entities/, /subscriptions/, /csourceRegistrations/, /csourceSubscriptions/, /temporal/entities/ and all of its sub-resources, and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.11‑1. Implementations shall not raise an error if they do not hold system generated temporal attributes.

-
-

Table 6.3.11-1: Including system generated temporal attributes: options parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-options -
-Comma separated list of strings -
-0..1 -
-When its value includes the keyword “sysAttrs”, a representation of NGSI-LD Elements shall be provided so that the system generated temporal attributes createdAt, modifiedAt and the system temporal attributeexpiresAt are included in the response payload body where known. In the case of temporal representations, also the system generated temporal attribute deletedAt is included, if the NGSI-LD Element has been deleted. -
-

6.3.12 Simplified or aggregated temporal representation of Entities

-

For HTTP GET and POST operations corresponding to “Retrieve Temporal Evolution of an Entity” (see clause 5.7.3) and “Query Temporal Evolution of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.12‑1.

-
-

Table 6.3.12-1: Temporal Entity representations: format + options parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

It shall be one of: “temporalValues”, “aggregatedValues”.

-

When its value is “temporalValues”, a simplified temporal representation of entities shall be provided as defined by clause 4.5.8.

-

When its value is “aggregatedValues”, an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword “temporalValues”, a simplified temporal representation of entities shall be provided as defined by clause 4.5.8.

-

When its value includes the keyword “aggregatedValues”, an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19.

-

Only one of the two keywords can be present in the values of the parameter.

-

If both format and options are present, the value of the format parameter shall take precedence.

-
-

6.3.13 Counting number of results

-

This clause implements the behaviour described in clause 4.13, in case of HTTP binding.

-

For HTTP operations corresponding to the operations listed in clause 4.12 (see Table 6.2‑1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.3.13‑1.

-
-

Table 6.3.13-1: Counting number of results: count parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-count -
-Boolean -
-0..1 -
-If true, then a special HTTP header (NGSILD-Results-Count) is set in the response. Regardless of how many entities are actually returned (maybe due to the limit URI parameter), the total number of matching results (e.g. number of Entities) is returned. -
-

This clause defines the specific HTTP binding mechanisms that can be useful to plan the limit and offset URI parameters for pagination, thus allowing to convey an overview of the number of entities in a system.

-

To get only the count itself, and no entities, the URI parameter limit may have the value “0”, and an empty array shall be returned as payload body.

-

Setting the URI parameter limit to zero without including the count URI parameter will result in a 400 BadRequest error.

-

6.3.14 Tenant specification

-

If the system implementing the NGSI-LD API supports multi-tenancy as described in clause 4.14 and clause 5.5.10, the Tenant, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header “NGSILD-Tenant”, whose value is the String identifying the Tenant. In case the target Tenant is the default Tenant, the HTTP header is omitted. If the HTTP header “NGSILD-Tenant” is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an “NGSILD-Tenant” HTTP header (clause 6.3.8).

-

6.3.15 GeoJSON representation of spatially bound entities

-

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), if the GeoJSON Accept header (“application/geo+json”) is present, implementations shall render the entities of the response in the GeoJSON format, as described in clause 5.2.29.

-

For GeoJSON representations, a GeoProperty may be selected as the geolocation to be used as the geometry within the GeoJSON payload. If no geometryProperty parameter is specified, then the location GeoProperty of the Entity is used.

-
-

Table 6.3.15-1: Selecting a geometry

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-geometryProperty -
-String -
-0..1 -
-If not present, “location” is used. -
-

6.3.16 Expiration time for cached @contexts

-

Implementations shall comply with the Expires header field (section 5.3 of IETF RFC 7234 [30]) or a max-age or s-maxage response directive of Cache-Control header field (section 5.2.2 of IETF RFC 7234 [30]) that may be present in the downloaded @context. This means that implementations shall periodically invalidate the “Cached” @contexts according to the headers mentioned above. Since origin servers do not always provide explicit expiration times, implementations should assign a heuristic (for instance according to IETF RFC 7234 [30] section 4.2.2) expiration time when an explicit time is not specified.

-

6.3.17 Distributed Operations Caching and Timeout Behaviour

-

The caching of response data received from forwarded HTTP GET requests is optionally supported by Context Brokers. For HTTP GET operations performed over the resources /entities and /entities/{entity-id}, where a Context Source Registration matches the request and a previous forwarded response has been cached and a subsequent request occurs before the Context Source Registration cacheDuration (as defined in Table 5.2.34‑1) has been reached, the result may incorporate data cached from a previous response. To indicate that data from a cache has been included in the response, the HTTP header “NGSILD-Warning” shall be included. The value shall match the IANA Warning Code [32] 110 - Response is Stale.

-

“NGSILD-Warning” HTTP headers shall also be used to indicate instances of abnormal behaviour for distributed HTTP GET operations performed over the resources /entities and /entities/{entity-id}.

-
-

Table 6.3.17-1: NGSI-LD Warning Codes

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-IANA Warning Code -
-Remarks -
-110 - Response is Stale -
-No request was made to a specified registration endpoint - data from a cached value has been reused and it has been incorporated into the response. -
-111 - Revalidation Failed -
-Although data was received from the registration endpoint within the specified timeout period, the payload of the response was invalid. This could occur if the payload was corrupted or a non-NGSI payload was received. -
-199 - Miscellaneous Warning -
-No response was received from the registration endpoint within the specified timeout period or a registration loop has been detected. -
-299 - Miscellaneous Persistent Warning -
-An error response (such as 403 - Forbidden) was received from the registration endpoint within the specified timeout period. This could occur if the Context Broker has insufficient access rights to retrieve the data. -
-

For distributed HTTP GET operations, registered context sources should always respond with a valid NGSI-LD payload. The Context Broker shall successfully parse this data and invalid non-NGSI-LD payloads shall be rejected and not incorporated into the overall response. It should be noted that a registration endpoint responding with no data and the HTTP status code 404 - Not Found should not be considered as abnormal behaviour for distributed operations.

-

For all other operations, which correspond to HTTP Unsafe methods, the error response should be as informative as possible.

-

In the case of an exclusive or redirect registration, where all of the data is held outside of the Context Broker and held in a single registered source, the following errors shall be returned:

-
-
    -
  • 508 Loop Detected – if the single registered source and tenant is registered to redirect back on to the Context Broker.
    • -
  • 504 Gateway Timeout - if the single registered source fails to respond in time.
    • -
  • 404 Not Found - if resources not found within the single registered source.
    • -
  • 502 Bad Gateway - if the single forwarded request fails for any other reason such as the Context Broker itself having insufficient access rights.
    • -
-
-

In the case of an inclusive or redirect registration, where an entity is distributed over multiple equally valid endpoints, but when updating the state of the distributed entity, an error response is returned from one or more registered sources:

-
-
    -
  • 207 Multi Status.
    • -
-
-

In the case of an auxiliary registration HTTP unsafe methods are not supported.

-

Whenever failures or timeouts occur, Context Brokers may optionally decline to make subsequent requests to the same registration endpoint until the cooldown period (as defined in Table 5.2.9-1) has been reached.

-

6.3.18 Limiting Distributed Operations

-

The parameter described in this clause limits the execution of an operation to a local Context Source or Context Broker (clause 5.5.13). It amends the matching Context Source Registrations behaviour as described in clause 5.12, in the case of the HTTP binding in order to avoid cascading distributed operations (see clause 4.3.6.4). For all operations the resources /entities/, /types/, /attributes/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ (and their respective child resources) implementations shall support the HTTP query parameter specified in Table 6.3.18‑1. The Registry API operations are always local and thus are not included here. Operations on a Snapshot (see clause 5.5.15) are always implicitly local scope, overriding setting the local parameter to false, i.e. such a setting is to be ignored by implementations.

-
-

Table 6.3.18-1: Limiting distributed operations: local parameter

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-local -
-Boolean -
-0..1 -
-If local=true then no Context Source Registrations shall be considered as matching to avoid cascading distributed operations (see clause 4.3.6.4) -
-

Furthermore, to avoid infinite loops, for all operations, the resources /entities/, /types/, /attributes/, /subscriptions/, /csourceSubscriptions/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ implementations shall fully support the HTTP Via Header (IETF RFC 7230 [27]) as specified in Table 6.3.18‑2. AnyContext Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source hostAlias (see clause 5.2.40) as the pseudonym.

-
-

Table 6.3.18-2: Request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-Via -
-String as defined in IETF RFC 7230 [27] -
-0..1 -
-If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations -
-

6.3.19 Extra information to provide when contacting Context Source

-

As specified in clauses 4.3.6.5 and 4.3.6.6, extra information to be provided when contacting a Context Source can be specified in the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration.

-

In the HTTP binding, if the “jsonldContext” key is present, the URL value is placed in an HTTP Link Header as described by the JSON-LD specification [2], section 6.2 and, whenever a payload body is present in the request, the HTTP Content-Type Header is set to “application/json”. For all other keys, a new custom HTTP header is added for each member named “key” of the key-value pairs that make up the array shall be generated and included in the HTTP list of headers. The content of each custom header shall be set equal to the content of the corresponding “value” member of the KeyValuePair, unless the special value “urn:ngsi-ld:request” has been set, in which case the value is to be taken from the triggering request, if present there. “Key” and “value” members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

-

Headers derived from other elements of the CSourceRegistration, e.g. “NGSILD-Tenant”, take precedence and cannot be overridden using contextSourceInfo. The same applies for headers generally set by HTTP itself, e.g. Content-length.

-

6.3.20 Invalid parameters

-

If an HTTP request for an operation contains parameters that are incompatible with the operation, or it contains values of the options parameter that are not supported by the operation, an HTTP error response of type InvalidRequest should be returned.

-

6.3.21 Optional profile information regarding versioning and datatype conformance

-

In the HTTP Binding, if an HTTP

-

Link header with a

-

profile

-

parameter

-

in accordance with IETF RFC 6906 [33], is found set to [<https://uri.etsi.org/ngsi-ld/profile/version]{.HTML_Code}> then implementations that are only partially capable of interpreting the datatypes conformant to the supplied NGSI-LD version may use this information to allow the payload to be accepted within the constraints of the current implementation (see clause 5.5.4) through amending the payload body and applying the fallbacks defined within clause 4.3.6.8.

-

6.3.22 Snapshot specification

-

If the system implementing the NGSI-LD API supports Snapshots as described in clause 4.3.7 and clause 5.5.15, the Snapshot, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header “NGSILD-Snapshot”, whose value is the identifier of the Snapshot. If the HTTP header “NGSILD-Snapshot” is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an “NGSILD-Snapshot” HTTP header (clause 6.3.8).

-

6.4 Resource: entities/

-

6.4.1 Description

-

This resource represents the entities known to an NGSI-LD system.

-

6.4.2 Resource definition

-

Resource URI:

-
-
    -
  • /entities/
    • -
-
-

6.4.3 Resource methods

-

6.4.3.1 POST

-

This method is bound to the operation “Create Entity” and shall exhibit the behaviour defined by clause 5.6.1, taking the entity to be created from the HTTP request payload body. Figure 6.4.3.1‑1 shows the Create Entity interaction and Table 6.4.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.4.3.1-1: Create Entity interaction

-
-
-

Table 6.4.3.1-1: Create Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the entity that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

The HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail member should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the entity or an exclusive or redirect registration defining the entity already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable Entity -
-

It is used to indicate that the operation is not available, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.4.3.2 GET

-

This method is associated to the operation “Query Entities” and shall exhibit the behaviour defined by clause 5.7.2, providing entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Query Entities” operations via POST is defined in clause 6.23. Figure 6.4.3.2‑1 shows the query entities interaction.

-
-

-
-
-

Figure 6.4.3.2-1: Query Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.4.3.2‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.2‑2 and Table 6.4.3.2‑3 describes the request body and possible responses.

-
-

Table 6.4.3.2-1: Query Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list of strings -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-

A synonym for a combination of the pick andq members. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entities and also included in the response, i.e. only Entities that contain at least one of the Attributes in attrs are to be included in the response, and only the Attributes listed in attrs are to be included in each of the Entities of the response.

-
-collation -
-String -
-0..1 -
-An ICU collation (see IETF RFC 6067 [36]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. -
-containedBy -
-Comma separated list of URIs -
-0..1 -
-List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present. -
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration.Only applicable if entityMap is set to true. -
-expandValues -
-Comma separated list of strings -
-0..1 -
-Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query. -
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored unless a geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-join -
-String -
-0..1 -
-The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: “flat”, “inline”,“@none”. -
-joinLevel -
-Positive Integer -
-0..1 -
-

Depth of Linked Entity retrieval to apply.

-

Only applicable if join parameter is present.

-
-jsonKeys -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute (Property or Relationship) name.

-

Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query.

-
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-orderBy -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or an Attribute name) appended with an optional sorting style (“asc”, “desc”, “dist-asc”, “dist-desc”)as per clause 4.23. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. -
-orderFrom -
-String -
-

0..1

-

It shall be one if orderBy uses order by distance

-
-Coordinates of a Geometry serialized as a string as per clause 4.10. It is part of Entity ordering. -
-orderGeometry -
-String -
-0..1 -
-A Geometry type (with the exception of GeometryCollection) as defined by the GeoJSON specification (IETF RFC 7946 [8]). It is part of Entity ordering. -
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-splitEntities -
-Boolean -
-0..1 -
-

If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally.

-

The parameter does not apply in case localis true.

-

The default value should be decided by implementation; it should be configurable.

-
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.4.3.2-2: Query Entities request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query operation is returned in the response. -
-
-

Table 6.4.3.2-3: Query Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

Entity[]

-
-

1

-
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of entities, unless the Accept Header indicates that the Entities are to be rendered as GeoJSON.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-

Entity[]

-
-

1

-
-

203 Non-Authoritative Information

-
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-GeoJSON FeatureCollection -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7. -
-

6.4.3.3 DELETE

-

This method is associated to the operation “Purge Entities” and shall exhibit the behaviour defined by clause 5.6.21, providing entities as part of the HTTP response payload body. Figure 6.4.3.3‑1 shows the query entities interaction.

-

-
-

Figure 6.4.3.3-1: Purge Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.4.3.3‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.3‑2 and Table 6.4.3.3‑3 describes the request body and possible responses.

-
-

Table 6.4.3.3-1: Purge Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-drop -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute name.

-

When defined, every Entity within the payload body is reduced to not contain the listed Entity members.

-
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored unless a geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-keep -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute name.

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.4.3.3-2: Purge Entities request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the set of Entities requested during the purge operation. The location of the EntityMap used in the purge operation is returned in the response -
-
-

Table 6.4.3.3-3: Purge Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.5 Resource: entities/{entityId}

-

6.5.1 Description

-

This resource represents an entity known to an NGSI-LD system.

-

6.5.2 Resource definition

-

Resource URI:

-
-
    -
  • /entities/{entityId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.5.2‑1.

-
-

Table 6.5.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the entity to be retrieved -
-

6.5.3 Resource methods

-

6.5.3.1 GET

-

This method is associated to the operation “Retrieve Entity” and shall exhibit the behaviour defined by clause 5.7.1. The Entity identifier is the value of the resource URI variable “entityId”. Figure 6.5.3.1‑1 shows the retrieve entity interaction.

-
-

-
-
-

Figure 6.5.3.1-1: Retrieve Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.1‑1, the request headers that shall be supported by implementations are those defined in Table 6.5.3.1‑2 and Table 6.5.3.1‑3 describes the request body and possible responses.

-
-

Table 6.5.3.1-1: Retrieve Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list of strings -
-0..1 -
-

A synonym for the pick parameter, except that id, type, scope are not allowed. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entity and included in the response. If the Entity does not have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not specified, no matching is performed and all Attributes related to the Entity shall be retrieved.

-
-containedBy -
-Comma separated list of URIs -
-0..1 -
-List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration.Only applicable if entityMap is set to true. -
-geometryProperty -
-String -
-0..1 -
-

It represents a GeoProperty name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the “geometry” element. By default, it shall be location.

-
-join -
-String -
-0..1 -
-The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: “flat”, “inline”, “@none” . -
-joinLevel -
-Positive Integer -
-0..1 -
-

Depth of Linked Entity retrieval to apply. Default is 1

-

Only applicable if join parameter is: “flat” or “inline”.

-
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). When defined, the listed Entity members are removed from the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval). -
-pick -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). When defined, the Entity is reduced down to only contain the listed Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval). -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.5.3.1-2: Retrieve Entity request Headers

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-NGSILD-EntityMap -
-URI -
-0..1 -
-If present, the EntityMap supplied is used for determining the extent of the Entity data requested during the retrieval operation. The location of the EntityMap used in the retreieval operation is returned in the response. -
-
-

Table 6.5.3.1-3: Retrieve Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

Entity

-
-

1

-
-

200 OK

-
-

A response body containing the JSON-LD representation of the target entity which consists only of the selected Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-

Entity

-
-

1

-
-

203 Non-Authoritative Information

-
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-GeoJSON Fature -
-1 -
-200 OK -
-

If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7. -
-

6.5.3.2 DELETE

-

This method is associated to the operation “Delete Entity” and shall exhibit the behaviour defined by clause 5.6.6. The Entity identifier is the value of the resource URI variable “entityId”. Figure 6.5.3.2‑1 shows the delete entity interaction.

-
-

-
-
-

Figure 6.5.3.2-1: Delete Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.2‑1 and Table 6.5.3.2‑2 describes the request body and possible responses.

-
-

Table 6.5.3.2-1: Delete Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.5.3.2-2: Delete Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.5.3.3 PUT

-

This method is bound to the “Replace Entity” operation and shall exhibit the behaviour defined by clause 5.6.18. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.3‑1 shows the Replace Entity interaction.

-
-

-
-
-

Figure 6.5.3.3-1: Replace Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.3‑1 and Table 6.5.3.3‑2 describes the request body and possible responses.

-
-

Table 6.5.3.3-1: Replace Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.5.3.3-2: Replace Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Entity to be replaced.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-The entity was replaced successfully. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

6.5.3.4 PATCH

-

This method is bound to the “Merge Entity” operation and shall exhibit the behaviour defined by clause 5.6.17. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.4‑1 shows the Merge Entity interaction.

-
-

-
-
-

Figure 6.5.3.4-1: Merge Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.5.3.4‑1 and Table 6.5.3.4‑2 describes the request body and possible responses.

-
-

Table 6.5.3.4-1: Merge Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-format -
-String -
-0..1 -
-

It shall be one of: “simplified” (or its synonym “keyValues”). Where present it indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4

-

In this case, when a merge operation applies to an existing Attribute the type field of the Attribute shall remain unchanged (any attempt to modify the type of an

-

Attribute shall result in a BadRequest error).

-
-lang -
-String -
-0..1 -
-

It represents the natural language of data held in the request.

-

When a merge operation applies to a pre-existing LanguageProperty and the value is supplied as a string or string array in the payload body, this query parameter shall be used to determine the key within the languageMap JSON Object to update.

-
-observedAt -
-String -
-0..1 -
-

It shall be a DateTime (see clause 4.6.3).

-

When a merge operation applies to a pre-existing Attribute which previously contained an observedAt sub-attribute, the value held in this query parameter shall be used if no specific observedAt sub-Attribute is found in the payload body.

-
-options -
-Comma separated list of strings -
-0..1 -
-

An alternative mechanism to include the format parameter. Deprecated

-

When its value includes the keyword“simplified” (or its synonym “keyValues”), this indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4.

-

If both format and options are present, the value of the format parameter shall take precedence.

-
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.5.3.4-2: Merge Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be merged.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were merged successfully. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

6.6 Resource: entities/{entityId}/attrs/

-

6.6.1 Description

-

This resource represents all the Attributes (Properties or Relationships) of an NGSI-LD Entity.

-

6.6.2 Resource definition

-

Resource URI:

-
-
    -
  • /entities/{entityId}/attrs
    • -
-
-

Resource URI variables for this resource are defined in Table 6.6.2‑1.

-
-

Table 6.6.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-

6.6.3 Resource methods

-

6.6.3.1 POST

-

This method is bound to the “Append Attributes” operation and shall exhibit the behaviour defined by clause 5.6.3. The Entity identifier is the value of the resource URI variable “entityId”. The data to be appended shall be contained in the HTTP request payload body. Figure 6.6.3.1‑1 shows the Append Attributes interaction.

-
-

-
-
-

Figure 6.6.3.1-1: Append Attributes interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.6.3.1‑1 and Table 6.6.3.1‑2 describes the request body and possible responses.

-
-

Table 6.6.3.1-1: Append Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-options -
-Comma separated list of strings -
-0..1 -
-“noOverwrite” indicates that no attribute overwrite shall be performed. -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.6.3.1-2: Append Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be added.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were appended successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

Only the Attributes included in the response payload body were successfully appended.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.6.3.2 PATCH

-

This method is bound to the “Update Attributes” operation and shall exhibit the behaviour defined by clause 5.6.2. The Entity identifier is the value of the resource URI variable “entityId”. The data to be updated shall be contained in the HTTP request payload body. Figure 6.6.3.2‑1 shows the Update Attributes interaction.

-
-

-
-
-

Figure 6.6.3.2-1: Update Attributes interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.6.3.2‑1 and Table 6.6.3.2‑2 describes the request body and possible responses.

-
-

Table 6.6.3.2-1: Update Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.6.3.2-2: Update Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing a complete representation of the Attributes to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were updated successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the updated array of UpdateResult (see clause 5.2.18) will be empty.

-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2. -
-

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

-

6.7.1 Description

-

This resource represents an attribute (Property or Relationship) of an NGSI-LD Entity.

-

6.7.2 Resource definition

-

Resource URI:

-
-
    -
  • /entities/{entityId}/attrs/{attrId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.7.2‑1.

-
-

Table 6.7.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-

6.7.3 Resource methods

-

6.7.3.1 PATCH

-

This method is bound to the “Partial Attribute Update” operation and shall exhibit the behaviour defined by clause 5.6.4. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. The Entity Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.1‑1 shows the Partial Attribute Update interaction.

-
-

-
-
-

Figure 6.7.3.1-1: Partial Attribute Update interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.7.3.1‑1 and Table 6.7.3.2‑2 describes the request body and possible responses.

-
-

Table 6.7.3.1-1: Partial Attribute Update URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.7.3.1-2: Partial Attribute Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity Fragment

-
-

1

-
-

Entity Fragment containing the elements of the attribute to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The attribute was updated successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2. -
-

6.7.3.2 DELETE

-

This method is associated to the operation “Delete Attribute” and shall exhibit the behaviour defined by clause 5.6.5. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. Figure 6.7.3.2‑1 shows the Delete Attribute interaction, Table 6.7.3.2‑1 shows the delete parameters to be supported and Table 6.7.3.2‑2 describes the request body and possible responses.

-
-

-
-
-

Figure 6.7.3.2-1: Delete Attribute interaction

-
-
-

Table 6.7.3.2-1: Delete Attribute URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-datasetId -
-String -
-0..1 -
-Shall be a valid URI. Specifies the datasetId of the dataset to be deleted. -
-deleteAll -
-Boolean -
-0..1 -
-If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted. -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.7.3.2-2: Delete Attribute request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) or attribute name not known to the system. see clause 6.3.2. -
-

6.7.3.3 PUT

-

This method is bound to the “Replace Attribute” operation and shall exhibit the behaviour defined by clause 5.6.19. The Entity identifier is the value of the resource URI variable “entityId”. The attribute name is the value of the resource URI variable “attrId”. The Attribute Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.3‑1 shows the Replace Attribute interaction.

-
-

-
-
-

Figure 6.7.3.3-1: Replace Attribute interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.7.3.3‑1 and Table 6.7.3.3‑2 describes the request body and possible responses.

-
-

Table 6.7.3.3-1: Replace Attribute URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-type -
-String -
-0..1 -
-Selection of Entity Types as per clause 4.17 -
-
-

Table 6.7.3.3-2: Replace Attribute request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Attribute Fragment

-
-

1

-
-

Attribute Fragment replacing the previous data.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The attribute was replaced successfully. -
-UpdateResult -
-1 -
-207 Multi-Status -
-

If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2. -
-

6.8 Resource: csourceRegistrations/

-

6.8.1 Description

-

This resource represents the context source registrations known to an NGSI-LD system.

-

6.8.2 Resource definition

-

Resource URI:

-
-
    -
  • /csourceRegistrations/
    • -
-
-

6.8.3 Resource methods

-

6.8.3.1 POST

-

This method is bound to the operation “Register Context Source” and shall exhibit the behaviour defined by clause 5.9.2, taking the context source registration to be created from the HTTP request payload body. Figure 6.8.3.1‑1 shows the Register Context Source interaction and Table 6.8.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.8.3.1-1: Register Context Source interaction

-
-
-

Table 6.8.3.1-1: Register Context Source request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

CSourceRegistration

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created context source registration. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the context source registration already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-

422 Unprocessable

-

Context Source Registration

-
-

It is used to indicate that the operation is not available see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.8.3.2 GET

-

This method is associated to the operation “Query Context Source Registrations” and shall exhibit the behaviour defined by clause 5.10.2, i.e. the parameters in the request describe entity related information, but instead of directly providing this entity information, the context source registration data, which describes context sources that can possibly provide the information, are returned as part of the HTTP response payload body. Figure 6.8.3.2‑1 shows the Query Context Source Registrations interaction.

-
-

-
-
-

Figure 6.8.3.2-1: Query Context Source Registrations interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.8.3.2‑1 and Table 6.8.3.2‑2 describes the request body and possible responses.

-
-

Table 6.8.3.2-1: Query Context Source Registrations URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-attrs -
-Comma separated list strings -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-

A synonym for a combination of the pick andq members. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.

-
-coordinates -
-String -
-

0..1

-

It shall be one if geometry or georel are present.

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-endTimeAt -
-String -
-0..1 -
-

It represents the endTimeAt parameter as defined by clause 4.1.

-

It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between”.

-
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present.

-

At least one among: type, attrs, q, or georel shall be present.

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geometryProperty -
-String -
-0..1 -
-

It represents a Property name.

-

In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.

-
-geoproperty -
-String -
-

0..1

-

It shall be ignored if no geoquery is present.

-
-It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present.

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids satisfying the query -
-lang -
-String -
-0..1 -
-

It represents the preferred natural language of the response.

-

It is used to reduce languageMaps to a string or string array property in a single preferred language.

-
-omit -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). -
-pick -
-Comma separated list of strings -
-0..1 -
-Each String is an Entity member (“id”, “type”, “scope” or a projected Attribute name). -
-q -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19). -
-timeAt -
-String -
-0..1 -
-

It represents the timeAt parameter as defined by clause 4.1.

-

It shall be a DateTime. Cardinality shall be 1 if timerel is present.

-
-timeproperty -
-String -
-

0..1

-

It shall be ignored if no temporal query is present.

-
-

It represents a Temporal Property name.

-

Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8).

-
-timerel -
-String -
-0..1 -
-

It represents the temporal relationship as defined by clause 4.1.

-

Allowed values: “before”, “after”, “between”.

-
-type -
-String -
-

0..1

-

At least one among: type, attrs, q, or georel shall be present.

-
-Selection of Entity Types as per clause 4.17. -
-
-

Table 6.8.3.2-2: Retrieve Context Source Registrations request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-CSourceRegistration[] -
-1 -
-200 OK -
-A response body containing the query result as an array of context source registrations. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.9 Resource: csourceRegistrations/{registrationId}

-

6.9.1 Description

-

This resource represents the context source registration, identified by registrationId, known to an NGSI-LD system.

-

6.9.2 Resource definition

-

Resource URI:

-
-
    -
  • /csourceRegistrations/{registrationId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.9.2‑1.

-
-

Table 6.9.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-registrationId -
-Id (URI) of the context source registration -
-

6.9.3 Resource methods

-

6.9.3.1 GET

-

This method is associated with the operation “Retrieve Context Source Registration” and shall exhibit the behaviour defined by clause 5.10.1. The registration identifier is the value of the resource URI variable “registrationId”. Figure 6.9.3.1‑1 shows the Retrieve Context Source Registration interaction and Table 6.9.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.1-1: Retrieve Context Source Registration interaction

-
-
-

Table 6.9.3.1-1: Retrieve Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-CSourceRegistration -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target context source registration. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2. -
-

6.9.3.2 PATCH

-

This method is bound to the “Update Context Source Registration” operation and shall exhibit the behaviour defined by clause 5.9.3. The context source registration identifier is the value of the resource URI variable “registrationId”. The context source registration to be updated shall be contained in the HTTP request payload body. Figure 6.9.3.2‑1 shows the Update Context Source Registration interaction and Table 6.9.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.2-1: Update Context Source Registration interaction

-
-
-

Table 6.9.3.2-1: Update Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

CSourceRegistration Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration that is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-The context source registration was successfully updated. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier not known to the system, see clause 6.3.2. -
-

6.9.3.3 DELETE

-

This method is associated to the operation “Delete Context Source Registration” and shall exhibit the behaviour defined by clause 5.9.4. The context source registration identifier is the value of the resource URI variable “registrationId”. Figure 6.9.3.3‑1 shows the Delete Context Source Registration interaction and Table 6.9.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.9.3.3-1: Delete Context Source Registration interaction

-
-
-

Table 6.9.3.3-1: Delete Context Source Registration request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2. -
-

6.10 Resource: subscriptions/

-

6.10.1 Description

-

This resource represents the subscriptions known to an NGSI-LD system.

-

6.10.2 Resource definition

-

Resource URI:

-
-
    -
  • /subscriptions/
    • -
-
-

6.10.3 Resource methods

-

6.10.3.1 POST

-

This method is bound to the operation “Create Subscription” and shall exhibit the behaviour defined by clause 5.8.1, taking the subscription to be created from the HTTP request payload body. Figure 6.10.3.1‑1 shows the Create Subscription interaction and Table 6.10.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.10.3.1-1: Create Subscription interaction

-
-
-

Table 6.10.3.1-1: Create Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the subscription that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the subscription already exists see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.10.3.2 GET

-

This method is associated to the operation “Query Subscriptions” and shall exhibit the behaviour defined by clause 5.8.4, providing the subscription data as part of the HTTP response payload body. Figure 6.10.3.2‑1 shows the Query Subscriptions interaction.

-
-

-
-
-

Figure 6.10.3.2-1: Query Subscriptions interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.10.3.2‑1 and Table 6.10.3.2‑2 describes the request body and possible responses.

-
-

Table 6.10.3.2-1: Query Subscriptions URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Number -
-0..1 -
-Maximum number of subscriptions to be retrieved -
-
-

Table 6.10.3.2-2: Query Subscriptions request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription[] -
-1 -
-200 OK -
-A response body containing a list of subscriptions. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.11 Resource: subscriptions/{subscriptionId}

-

6.11.1 Description

-

This resource represents a subscription known to an NGSI-LD system.

-

6.11.2 Resource definition

-

Resource URI:

-
-
    -
  • /subscriptions/{subscriptionId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.11.2‑1.

-
-

Table 6.11.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-subscriptionId -
-Id (URI) of the concerned subscription -
-

6.11.3 Resource methods

-

6.11.3.1 GET

-

This method is associated to the operation “Retrieve Subscription” and shall exhibit the behaviour defined by clause 5.8.3. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.1‑1 shows the Retrieve Subscription interaction and Table 6.11.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.1-1: Retrieve Subscription interaction

-
-
-

Table 6.11.3.1-1: Retrieve Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.11.3.2 PATCH

-

This method is associated to the operation “Update Subscription” and shall exhibit the behaviour defined by clause 5.8.2. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.2‑1 shows the Update Subscription interaction and Table 6.11.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.2-1: Update Subscription interaction

-
-
-

Table 6.11.3.2-1: Update Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription Fragment

-
-

1

-
-

Subscription Fragment including id, type and any other subscription field to be changed

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.11.3.3 DELETE

-

This method is associated to the operation “Delete Subscription” and shall exhibit the behaviour defined by clause 5.8.5. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.11.3.3‑1 shows the Delete Subscription interaction and Table 6.11.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.11.3.3-1: Delete Subscription interaction

-
-
-

Table 6.11.3.3-1: Delete Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.12 Resource: csourceSubscriptions/

-

6.12.1 Description

-

This resource represents the context source registration subscriptions known to an NGSI-LD system.

-

6.12.2 Resource definition

-

Resource URI:

-
-
    -
  • /csourceSubscriptions/
    • -
-
-

6.12.3 Resource methods

-

6.12.3.1 POST

-

This method is bound to the operation “Create Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.2, taking the context source registration subscription to be created from the HTTP request payload body. Figure 6.12.3.1‑1 shows the Create Context Source Registration Subscription interaction and Table 6.12.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.12.3.1-1: Create Context Source Registration Subscription interaction

-
-
-

Table 6.12.3.1-1: Create Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the context source registration subscription that is to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created context source registration subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the context source registration subscription already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.12.3.2 GET

-

This method is associated to the operation “Query Context Source Registration Subscriptions” and shall exhibit the behaviour defined by clause 5.11.5, providing the context source registration subscription data as part of the HTTP response payload body. Figure 6.12.3.2‑1 shows the Query Context Source Registration Subscriptions interaction.

-
-

-
-
-

Figure 6.12.3.2-1: Query Context Source Registration Subscriptions interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.12.3.2‑1 and Table 6.12.3.2‑2 describes the request body and possible responses.

-
-

Table 6.12.3.2-1: Query Context Source Registration Subscriptions URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-limit -
-Number -
-0..1 -
-Maximum number of subscriptions to be retrieved -
-
-

Table 6.12.3.2-2: Query Context Source Registration Subscriptions request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription[] -
-1 -
-200 OK -
-A response body containing a list of context source registration subscriptions. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.13 Resource: csourceSubscriptions/{subscriptionId}

-

6.13.1 Description

-

This resource represents the context source registration subscription, identified by subscriptionId, known to an NGSI-LD system.

-

6.13.2 Resource definition

-

Resource URI:

-
-
    -
  • /csourceSubscriptions/{subscriptionId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.13.2‑1.

-
-

Table 6.13.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-subscriptionId -
-Id (URI) of the concerned context source registration subscription -
-

6.13.3 Resource methods

-

6.13.3.1 GET

-

This method is associated to the operation “Retrieve Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.4. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.1‑1 shows the Retrieve Context Source Registration interaction and Table 6.13.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.1-1: Retrieve Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Subscription -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the target context source registration subscription. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.13.3.2 PATCH

-

This method is associated to the operation “Update Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.3. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.2‑1 shows the Update Context Source Registration Subscription interaction and Table 6.13.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.2-1: Update Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.2-1: Update Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Subscription Fragment

-
-

1

-
-

Subscription Fragment including id, type and any other context source registration subscription field to be changed

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.13.3.3 DELETE

-

This method is associated to the operation “Delete Context Source Registration Subscription” and shall exhibit the behaviour defined by clause 5.11.6. The subscription identifier is the value of the resource URI variable “subscriptionId”. Figure 6.13.3.3‑1 shows the Delete Context Source Registration Subscription interaction and Table 6.13.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.13.3.3-1: Delete Context Source Registration Subscription interaction

-
-
-

Table 6.13.3.3-1: Delete Context Source Registration Subscription request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2. -
-

6.14 Resource: entityOperations/create

-

6.14.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation for the NGSI-LD API.

-

6.14.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/create
    • -
-
-

6.14.3 Resource methods

-

6.14.3.1 POST

-

This method is associated to the operation “Batch Entity Creation” and shall exhibit the behaviour defined by clause 5.6.7. Figure 6.14.3.1‑1 shows the operation interaction and Table 6.14.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.14.3.1-1: Batch Entity Creation interaction

-
-
-

Table 6.14.3.1-1: Batch Entity Creation request bodyand possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of entities to be created

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-String[] -
-1 -
-201 Created -
-If all entities have been successfully created, an array of Strings containing URIs is returned in the response. Each URI represents the Entity ID of a created entity. There is no restriction as to the order of the Entity IDs. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created entities, while the second array (errors) contains information about the error for each of the entities that could not be created. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.15 Resource: entityOperations/upsert

-

6.15.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation or update for the NGSI-LD API.

-

6.15.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/upsert
    • -
-
-

6.15.3 Resource methods

-

6.15.3.1 POST

-

This method is associated to the operation “Batch Entity Creation or Update (Upsert)” and shall exhibit the behaviour defined by clause 5.6.8. Figure 6.15.3.1‑1 shows the operation interaction and Table 6.15.3.1‑1 describes the request body and possible responses.

-

The options query parameter for this request can take the following values:

-
-
    -
  • “replace”. Indicates that all the existing Entity content shall be replaced (default mode);
    • -
  • “update”. Indicates that existing Entity content shall be updated.
    • -
-
-
-

-
-
-

Figure 6.15.3.1-1: Batch Entity Creation or Update interaction

-
-
-

Table 6.15.3.1-1: Batch Entity Creation or Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of entities to be created/updated

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-String[] -
-1 -
-201 Created -
-If all entities not existing prior to this request have been successfully created and the others have been successfully updated, an array of String (with the URIs representing the Entity IDs of the created entities only) is returned in the response. There is no restriction as to the order of the Entity IDs. The merely updated entities do not take part in the response (corresponding to 204 No Content returned in the case of updates). -
-N/A -
-N/A -
-204 No Content -
-If all entities already existed and are successfully updated, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created or updated entities, while the second array (errors) contains information about the error for each of the entities that could not be created or updated. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.16 Resource: entityOperations/update

-

6.16.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity update for the NGSI-LD API.

-

6.16.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/update
    • -
-
-

6.16.3 Resource methods

-

6.16.3.1 POST

-

This method is associated to the operation “Batch Entity Update” and shall exhibit the behaviour defined by clause 5.6.9. Figure 6.16.3.1‑1 shows the operation interaction and Table 6.16.3.1‑1 describes the request body and possible responses.

-

The options query parameter for this request can take the following values:

-
-
    -
  • “noOverwrite”. Indicates that no attribute overwrite shall be performed.
    • -
-
-
-

-
-
-

Figure 6.16.3.1-1: Batch Entity Update interaction

-
-
-

Table 6.16.3.1-1: Batch Entity Update request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of Entities to be updated

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities have been successfully updated, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully updated entities, while the second array (errors) contains information about the error for each of the entities that could not be updated. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.17 Resource: entityOperations/delete

-

6.17.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity deletion for the NGSI-LD API.

-

6.17.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/delete
    • -
-
-

6.17.3 Resource methods

-

6.17.3.1 POST

-

This method is associated to the operation “Batch Entity Delete” and shall exhibit the behaviour defined by clause 5.6.10. Figure 6.17.3.1‑1 shows the operation interaction and Table 6.17.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.17.3.1-1: Batch Entity Delete interaction

-
-
-

Table 6.17.3.1-1: Batch Entity Delete request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

String[]

-
-

1

-
-

Array of String (URIs representing Entity IDs) to be deleted

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities existed and have been successfully deleted, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully deleted entities, while the second array (errors) contains information about the error for each of the entities that could not be deleted. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.18 Resource: temporal/entities/

-

6.18.1 Description

-

This resource represents the Temporal Evolution of Entities known to an NGSI-LD system.

-

6.18.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entities/
    • -
-
-

6.18.3 Resource methods

-

6.18.3.1 POST

-

This method is associated to the operation “Create or Update Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.11, taking the temporal representation of Entity to be created from the HTTP request payload body. Figure 6.18.3.1‑1 shows this interaction and Table 6.18.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity interaction

-
-
-

Table 6.18.3.1-1: Create or Update Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the temporal representation of the Entity that is to be created (or updated).

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-Upon creation success, the HTTP response shall include a “Location” HTTP header that contains the relative path of the created entity. -
-N/A -
-N/A -
-204 No Content -
-Upon update success. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail member should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable Entity -
-

It is used to indicate that the operation is not available, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.18.3.2 GET

-

This method is associated to the operation “Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.7.4, providing the Temporal Evolution of the matching Entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Query Temporal Evolution of Entities” operations via POST is defined in clause 6.24. Figure 6.18.3.2‑1 shows this interaction.

-
-

-
-
-

Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.18.3.2‑1 and Table 6.18.3.2‑2 describes the request body and possible responses.

-
-

Table 6.18.3.2-1: Query Temporal Evolution of Entities URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-aggrMethods -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if aggregatedValues is present in the options parameter

-
-Each String represents an aggregation method, as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-attrs -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if type is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-

A synonym for a combination of the pick andq parameters. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.

-
-collation -
-String -
-0..1 -
-An ICU collation (see IETF RFC 6067 [36]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering. -
-coordinates -
-String -
-

0..1

-

It shall be one if georel or geometry are present

-
-Coordinates serialized as a string as per clause 4.10. It is part of geoquery. -
-csf -
-String -
-0..1 -
-Context Source filter as per clause 4.9. -
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-endTimeAt -
-String -
-0..1 -
-It representing the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to “between”. -
-entityMap -
-Boolean -
-0..1 -
-If true, the location of the EntityMap used in the operation is returned in the response. -
-entityMapLifetime -
-String -
-0..1 -
-Suggested duration, represented in ISO 8601 format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true. -
-expandValues -
-Comma separated list of strings -
-0..1 -
-Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query. -
-geometry -
-String -
-

0..1

-

It shall be 1 if georel or coordinates are present

-
-Geometry as per clause 4.10. It is part of geoquery. -
-geoproperty -
-String -
-

0..1

-

It shall be ignored if no geoquery is present

-
-The name of the GeoProperty that contains the geospatial data that will be used to resolve the geoquery. By default, will be location. (See clause 4.7). -
-georel -
-String -
-

0..1

-

It shall be 1 if geometry or coordinates are present

-
-Geo relationship as per clause 4.10. It is part of geoquery. -
-id -
-Comma separated list of strings -
-0..1 -
-Each String shall be a valid URI. List of entity ids to be retrieved. -
-idPattern -
-Regular expression as defined by [11] -
-0..1 -
-Regular expression that shall be matched by entity ids. -
-jsonKeys -
-Comma separated list of strings -
-0..1 -
-

Each String is an Attribute (Property or Relationship) name.

-

Values of the identified attributes are to be considered uninterpretable as JSON-LD and should not be expanded against the supplied @context using JSON-LD type coercion prior to executing the query.

-
-lang -
-String -
-0..1 -
-It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language. -
-lastN -
-Positive integer -
-0..1 -
-Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. -
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-orderBy -
-String -
-0..1 -
-The Entity member (“id”) appended with an optional sorting style (“asc”, “desc”)as per clause 4.23. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering. -
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-q -
-String -
-0..1 -
-Query as per clause 4.9. -
-scopeQ -
-String -
-0..1 -
-Scope query (see clause 4.19) -
-splitEntities -
-Boolean -
-0..1 -
-

If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when applying any kind of filters (q, geoQ, scopeQ, Attributes etc.). If false it is expected that Context Broker and/or Context Source always have complete Entities, which allows applying filters locally.

-

The parameter does not apply in case localis true.

-

The default value should be decided by implementation; it should be configurable.

-
-timeAt -
-String -
-1 -
-representing the timeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-timeproperty -
-String -
-0..1 -
-It represents a Temporal Property name. Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8). -
-timerel -
-String -
-1 -
-It represents the temporal relationship as defined by clause 4.11. Allowed values: “before”, “after”, “between”. -
-type -
-String -
-

0..1

-

It shall be 1 if attrs is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).

-
-Selection of Entity Types as per clause 4.17. “*” is also allowed as a value and local is implicitly set to true and shall not be explicitly set tofalse. -
-
-

Table 6.18.3.2-2: Query Temporal Evolution of Entitiesrequest body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of temporal representation of Entities.

-

If an EntityMap has been requested, the HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource used in the operation.

-
-EntityTemporal[] -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.19 Resource: temporal/entities/{entityId}

-

6.19.1 Description

-

This resource is associated to the Temporal Evolution of an Entity known to an NGSI-LD system.

-

6.19.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entities/{entityId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.19.2‑1.

-
-

Table 6.19.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the entity to be retrieved -
-

6.19.3 Resource methods

-

6.19.3.1 GET

-

This method is associated to the operation “Retrieve Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.7.3. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.1‑1 shows the retrieve temporal representation of an entity interaction.

-
-

-
-
-

Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction

-
-

The URL parameters that shall be supported are those defined in Table 6.19.3.1‑1 and Table 6.19.3.1‑2 describes the request body and possible responses.

-
-

Table 6.19.3.1-1: Retrieve Temporal Evolution of an Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-aggrMethods -
-Comma separated list of strings -
-

0..1

-

It shall be 1 if aggregatedValues is present in the options parameter

-
-Each String represents the aggregation methods as defined by clause 4.5.19. Only applicable if “aggregatedValues” is present in the format or options parameter. -
-aggrPeriodDuration -
-String -
-0..1 -
-

It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query.

-

Only applicable if “aggregatedValues”is present in the format or options parameter.

-
-attrs -
-Comma separated list of strings -
-0..1 -
-

A synonym for the pick parameter, except that id, type, scope are not allowed. Deprecated

-

Each String is an Attribute (Property or Relationship) name. List of Attributes to be retrieved. If not specified, all Attributes related to the temporal representation of an Entity shall be retrieved.

-
-datasetId -
-Comma separated list of strings -
-0..1 -
-Shall be valid URIs, “@none” for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5. -
-endTimeAt -
-String -
-

0..1

-

It shall be 1 if timerel is equal to “between”

-
-It represents the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-lang -
-String -
-0..1 -
-It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language. -
-lastN -
-Positive integer -
-0..1 -
-Only the last n Attribute instances (under the concerned time interval) shall be retrieved. -
-omit -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, the listed Entity members are removed from each Entity within the payload.

-
-pick -
-Comma separated list of strings -
-0..1 -
-

Each String is an Entity member (“id”, “type”, “scope” or an Attribute name).

-

When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.

-
-timeAt -
-String -
-

0..1

-

It shall be 1 if timerel is present

-
-It represents the timeAt parameter as defined by clause 4.11. It shall be a DateTime. -
-timeproperty -
-String -
-0..1 -
-It represents a Temporal Property name. Allowed values: “observedAt”, “createdAt”, “modifiedAt” and “deletedAt”. If not specified, the default is “observedAt”. (See clause 4.8). -
-timerel -
-String -
-

0..1

-

It shall be 1 if timeAt is present

-
-It represents the Temporal Relationship as defined by clause 4.11. Allowed values: “before”, “after”, “between”. -
-
-

Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal -
-1 -
-200 OK -
-A response body containing the JSON-LD temporal representation of the target Entity containing the selected Attributes. -
-EntityTemporal -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

6.19.3.2 DELETE

-

This method is associated to the operation “Delete Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.16. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.2‑1 shows the delete entity interaction and Table 6.19.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction

-
-
-

Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

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

-

6.20.1 Description

-

This resource represents all the Attributes (Properties or Relationships) of a Temporal Evolution of an Entity.

-

6.20.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entities/{entityId}/attrs/
    • -
-
-

Resource URI variables for this resource are defined in Table 6.20.2‑1.

-
-

Table 6.20.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-

6.20.3 Resource methods

-

6.20.3.1 POST

-

This method is bound to the “Add Attributes to Temporal Evolution of an Entity” operation and shall exhibit the behaviour defined by clause 5.6.12. The Entity identifier is the value of the resource URI variable entityId. The data to be added shall be contained in the HTTP request payload body. Figure 6.20.3.1‑1 shows the Add Attributes interaction and Table 6.20.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity interaction

-
-
-

Table 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal Fragment

-
-

1

-
-

EntityTemporal Fragment containing a complete representation of the Attribute instances to be added.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No content -
-All the Attributes were added successfully. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2. -
-

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

-

6.21.1 Description

-

This resource represents an Attribute (Property or Relationship) of a Temporal Evolution of an Entity.

-

6.21.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entities/{entityId}/attrs/{attrId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.21.2‑1.

-
-

Table 6.21.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-

6.21.3 Resource methods

-

6.21.3.1 DELETE

-

This method is associated to the operation “Delete Attribute from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.13. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. Figure 6.21.3.1‑1 shows the “Delete Attribute from Temporal Evolution of an Entity” interaction, Table 6.21.3.1‑1 shows the delete parameters to be supported and Table 6.21.3.1‑2 describes the request body and possible responses.

-
-

-
-
-

Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity interaction

-
-
-

Table 6.21.3.1-1: Delete Attribute from Temporal Evolution of an Entity URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-name -
-Data Type -
-Cardinality -
-Remarks -
-datasetId -
-String -
-0..1 -
-Shall be a valid URI. Specifies the datasetId of the dataset to be deleted. -
-deleteAll -
-Boolean -
-0..1 -
-If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted. -
-
-

Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI) or Attribute name not known to the system. See clause 6.3.2. -
-

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

-

6.22.1 Description

-

This resource represents an Attribute (Property or Relationship) instance of a Temporal Evolution of an Entity.

-

6.22.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entities/{entityId}/attrs/{attrId}/{instanceId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.22.2‑1.

-
-

Table 6.22.2-1: URI variables

-
- ---- - - - - - - - - - - - - - - - - - - - - -
-Name -
-Definition -
-entityId -
-Id (URI) of the concerned entity -
-attrId -
-Attribute name (Property or Relationship) -
-instanceId -
-Id (URI) identifying a particular Attribute instance -
-

6.22.3 Resource methods

-

6.22.3.1 PATCH

-

This method is associated to the operation “Modify attribute instance from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.14. The Entity identifier is the value of the resource URI variable entityId. The attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.1‑1 shows the Modify Attribute instance interaction and Table 6.22.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution interaction

-
-
-

Table 6.22.3.1-1: Modify Attribute instance from Temporal Evolution request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityTemporal Fragment

-
-

1

-
-

EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2. -
-

6.22.3.2 DELETE

-

This method is associated to the operation “Delete Attribute instance from Temporal Evolution of an Entity” and shall exhibit the behaviour defined by clause 5.6.15. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.2‑1 shows the Delete Attribute instance interaction and Table 6.22.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity interaction

-
-
-

Table 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2. -
-

6.23 Resource: entityOperations/query

-

6.23.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.4.3.2, which performs the “Query Entity” operation (defined by clause 5.7.2) by means of a GET method. The reason to provide an alternative via POST is that, using GET:

-
-
    -
  1. The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
    2. -
  2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.
    3. -
-
-

6.23.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/query
    • -
-
-

6.23.3 Resource methods

-

6.23.3.1 POST

-

This method is associated to the operation “Query Entities” and shall exhibit the behaviour defined by clause 5.7.2. Figure 6.23.3.1‑1 shows the operation interaction and Table 6.23.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.23.3.1-1: Query Entity via POST interaction

-
-
-

Table 6.23.3.1-1: Query Entity via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Entity[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of Entities.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-GeoJSON FeatureCollection -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-Entity[] -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.24 Resource: temporal/entityOperations/query

-

6.24.1 Description

-

A sub-resource, pertaining to the temporal/entityOperations/ resource, intended to enable temporal querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.18.3.2, which performs the “Query Temporal Evolution of Entities” (defined by clause 5.7.4) operation by means of a GET method. The reason to provide an alternative via POST is that, using GET:

-
-
    -
  1. The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
    2. -
  2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.
    3. -
-
-

6.24.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entityOperations/query
    • -
-
-

6.24.3 Resource methods

-

6.24.3.1 POST

-

This method is associated to the operation “Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.7.4. Figure 6.24.3.1‑1 shows the operation interaction and Table 6.24.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.24.3.1-1: Temporal Query Entity via POST interaction

-
-
-

Table 6.24.3.1-1: Temporal Query Entity via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTemporal[] -
-1 -
-

200 OK

-

201 Created (in case an EntityMap has been (re)created)

-
-

A response body containing the query result as a list of Entities.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.25 Resource: types/

-

6.25.1 Description

-

This resource represents the entity types available in an NGSI-LD system.

-

6.25.2 Resource definition

-

Resource URI:

-
-
    -
  • /types/
    • -
-
-

6.25.3 Resource methods

-

6.25.3.1 GET

-

This method is associated to the operations “Retrieve Available Entity Types” and “Retrieve Details of Available Entity Types” (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.5 and 5.7.6 respectively.

-
-

-
-
-

Figure 6.25.3.1-1: Retrieve Available Entity Types interaction

-
-

The request parameters that shall be supported are those defined in Table 6.25.3.1‑1 and Table 6.25.3.1‑2 describes the request body and possible responses.

-
-

Table 6.25.3.1-1: Retrieve Available Entity Types URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-If true, then detailed entity type information represented as an array with elements of the Entity Type data structure (clause 5.2.25) is to be returned -
-
-

Table 6.25.3.1-2: Retrieve Available Entity Types request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTypeList -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the EntityTypeList (clause 5.2.24) is to be returned, unless details=true is specified. -
-EntityType[] -
-1 -
-200 OK -
-If details=true is specified, a response body containing a JSON-LD array with elements of the EntityType data structure (clause 5.2.25) is to be returned. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.26 Resource: types/{type}

-

6.26.1 Description

-

This resource represents the specified entity type for which entity instances are available in an NGSI-LD system.

-

6.26.2 Resource definition

-

Resource URI:

-
-
    -
  • /types/{type}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.26.2‑1.

-
-

Table 6.26.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-type -
-Name of the entity type for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. -
-

6.26.3 Resource methods

-

6.26.3.1 GET

-

This method is associated to the operation “Retrieve Available Entity Type Information” and shall exhibit the behaviour defined by clause 5.7.7. The entity type is the value of the resource URI variable “type”. Figure 6.26.3.1‑1 shows the retrieve available entity type interaction.

-
-

-
-
-

Figure 6.26.3.1-1: Retrieve Available Entity Type interaction

-
-

Table 6.26.3.1‑1 describes the request body and possible responses.

-
-

Table 6.26.3.1-1: Retrieve Available Entity Type request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityTypeInfo -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the detailed information about the available entity type. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an entity type not known to the system, see clause 6.3.2. -
-

6.27 Resource: attributes/

-

6.27.1 Description

-

This resource represents the attributes available in an NGSI-LD system.

-

6.27.2 Resource definition

-

Resource URI:

-
-
    -
  • /attributes/
    • -
-
-

6.27.3 Resource methods

-

6.27.3.1 GET

-

This method is associated to the operations “Retrieve Available Attributes” and “Retrieve Details of Available Attributes” (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.8 and 5.7.9 respectively.

-
-

-
-
-

Figure 6.27.3.1-1: Retrieve Available Attributes interaction

-
-

The request parameters that shall be supported are those defined in Table 6.27.3.1‑1 and Table 6.27.3.1‑2 describes the request body and possible responses.

-
-

Table 6.27.3.1-1: Retrieve Available Attributes URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-If true, then detailed attribute information represented as an array with elements of the Attribute data structure (clause 5.2.28) is to be returned -
-
-

Table 6.27.3.1-2: Retrieve Available Attributes request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-AttributeList -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the AttributeList (clause 5.2.27) is to be returned, unless details=true is specified. -
-Attribute[] -
-1 -
-200 OK -
-If details=true is specified, a response body containing a JSON-LD array with elements of the Attribute data structure (clause 5.2.28) is to be returned. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.28 Resource: attributes/{attrId}

-

6.28.1 Description

-

This resource represents the specified attribute that belongs to entity instances existing within the NGSI-LD system.

-

6.28.2 Resource definition

-

Resource URI:

-
-
    -
  • /attributes/{attrId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.28.2‑1.

-
-

Table 6.28.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-attrId -
-Name of the attribute for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. -
-

6.28.3 Resource methods

-

6.28.3.1 GET

-

This method is associated to the operation “Retrieve Available Attribute Information” and shall exhibit the behaviour defined by clause 5.7.10. The attribute is the value of the resource URI variable “attrId”. Figure 6.28.3.1‑1 shows the retrieve available attribute information interaction.

-
-

-
-
-

Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction

-
-

Table 6.28.3.1‑1 describes the request body and possible responses.

-
-

Table 6.28.3.1-1: Retrieve Available Attribute Information request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Attribute -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the detailed information about the available attribute. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an attribute name not known to the system, see clause 6.3.2. -
-

6.29 Resource: jsonldContexts/

-

6.29.1 Description

-

This resource represents the @contexts known to an NGSI-LD system.

-

6.29.2 Resource definition

-

Resource URI:

-
-
    -
  • /jsonldContexts/
    • -
-
-

6.29.3 Resource methods

-

6.29.3.1 POST

-

This method is bound to the operation “Add @context” and shall exhibit the behaviour defined by clause 5.13.2, taking the @context to be added from the HTTP request payload body. Figure 6.29.3.1‑1 shows the Add @context interaction and Table 6.29.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.29.3.1-1: Add @context interaction

-
-
-

Table 6.29.3.1-1: Add @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

JSON Object

-
-

1

-
-

Payload body in the request contains a JSON object that has a root node named @context, which represents a JSON-LD “local context”.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the local relative path of the added @context. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.29.3.2 GET

-

This method is associated to the operation “List @contexts” and shall exhibit the behaviour defined by clause 5.13.3, and it provides information about stored @contexts as part of the HTTP response payload body. Figure 6.29.3.2‑1 shows the List @contexts interaction.

-
-

-
-
-

Figure 6.29.3.2-1: List @contexts interaction

-
-

The request parameters that shall be supported by implementations are those defined in Table 6.29.3.2‑1 and Table 6.29.3.2‑2 describes the request body and possible responses.

-
-

Table 6.29.3.2-1: List @contexts URL parameters

-
- ------ - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-Whether a list of URLs or a more detailed list of JSON Objects is requested -
-kind -
-String -
-0..1 -
-Can be either “Cached”, “Hosted”, or “ImplicitlyCreated” -
-
-

Table 6.29.3.2-2: List @contexts request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

String[]

-

or

-

JSON Object[]

-
-1 -
-200 OK -
-A response body containing a list of URLs or a list of JSON Objects, as defined in clause 5.13.3.5, representing metadata about stored @contexts. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.30 Resource: jsonldContexts/{contextId}

-

6.30.1 Description

-

This resource represents a JSON-LD @context stored in the broker’s internal @context storage.

-

6.30.2 Resource definition

-

Resource URI:

-
-
    -
  • /jsonldContexts/{contextId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.30.2‑1.

-
-

Table 6.30.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-contextId -
-Local identifier of the @context to be managed (served or deleted). For @contexts of kind “Cached” this can also be the original URL the broker downloaded the @context from. -
-

6.30.3 Resource methods

-

6.30.3.1 GET

-

This method is associated to the operation “Serve @context” and shall exhibit the behaviour defined by clause 5.13.4. The @context identifier is the value of the resource URI variable “contextId”. Figure 6.30.3.1‑1 shows the HTTP Serve @context interaction.

-
-

-
-
-

Figure 6.30.3.1-1: Serve @context interaction

-
-

The request parameters that shall be supported by implementations are those defined in Table 6.30.3.1‑1 and Table 6.30.3.1‑2 describes the request body and possible responses.

-
-

Table 6.30.3.1-1: Serve @contexts URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-details -
-Boolean -
-0..1 -
-Whether the content of the @context or its metadata is requested -
-
-

Table 6.30.3.1-2: Serve @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-

JSON Object

-
-

1

-
-

200 OK

-
-

If the parameter details is false or missing, response body contains a JSON object that has a root node named @context, which represents a JSON-LD “local context”.

-

If the parameter details is true, response body contains a JSON object as defined in clause 5.13.4.5, which metadata of a JSON-LD “local context”.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

400 Bad Request

-
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-422 Unprocessable -
-It is used when a client indicated an @context of type “Cached”, see clause 6.3.2. -
-

6.30.3.2 DELETE

-

This method is associated to the operation “Delete and Reload @context” and shall exhibit the behaviour defined by clause 5.13.5. The Entity identifier is the value of the resource URI variable “contextId”. Figure 6.30.3.2‑1 shows the delete entity interaction. The request parameters that shall be supported are those defined in Table 6.30.3.2‑1 and Table 6.30.3.2‑2 describes the request body and possible responses.

-
-

Table 6.30.3.2-1: Delete and Reload @context URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Cardinality -
-Remarks -
-reload -
-Boolean -
-0..1 -
-indicates to perform a download and replace of the @context, as specified in clause 5.13.5.4. -
-
-

-
-
-

Figure 6.30.3.2-1: Delete and Reload @context interaction

-
-
-

Table 6.30.3.2-2: Delete and Reload @context request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-504 Gateway Timeout -
-It is used when re-downloading fails. -
-

6.31 Resource: entityOperations/merge

-

6.31.1 Description

-

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity merge for the NGSI-LD API.

-

6.31.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityOperations/merge
    • -
-
-

6.31.3 Resource methods

-

6.31.3.1 POST

-

This method is associated to the operation “Batch Entity Merge” and shall exhibit the behaviour defined by clause 5.6.20. Figure 6.31.3.1‑1 shows the operation interaction and Table 6.31.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.31.3.1-1: Batch Entity Merge interaction

-
-
-

Table 6.31.3.1-1: Batch Entity Merge request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Entity[]

-
-

1

-
-

Array of Entities to be merged.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Code

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-If all entities have been successfully merged, there is no payload body in the response. -
-BatchOperationResult -
-1 -
-207 Multi-Status -
-

If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully merged entities, while the second array (errors) contains information about the error for each of the entities that could not be merged-patched. There is no restriction as to the order of the Entity IDs in the arrays.

-

If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation.

-

In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure.

-

Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.32 Resource: entityMaps/{entityMapId}

-

6.32.1 Description

-

This resource represents an EntityMap available in the broker’s internal storage or memory.

-

6.32.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityMaps/{entityMapId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.32.2‑1.

-
-

Table 6.32.2-1: URI variables

-
- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-entityMapId -
-Id (URI) of the EntityMap to be retrieved, updated or deleted. -
-

6.32.3 Resource methods

-

6.32.3.1 GET

-

This method is associated to the operation “Retrieve EntityMap” and shall exhibit the behaviour defined by clause 5.14.1. The EntityMap identifier is the value of the resource URI variable “entityMapId”. Figure 6.32.3.1‑1 shows the Retrieve EntityMap interaction and Table 6.32.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.1-1: Retrieve EntityMap

-
-
-

Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-Response Body -
-Data Type -
-Cardinality -
-Response Codes -
-Remarks -
-EntityMap -
-1 -
-200 OK -
-

A response body containing the JSON-LD representation of the target entity.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

404 Not Found

-
-

It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

-
-

6.32.3.2 PATCH

-

This method is associated to the operation “Update EntityMap” and shall exhibit the behaviour defined by clause 5.14.2. The EntityMap identifier is the value of the resource URI variable “entityMapId”. Figure 6.32.3.2‑1 shows the Update EntityMap interaction and Table 6.32.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.2-1: Update EntityMap

-
-
-

Table 6.32.3.2-1: Update EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

EntityMap Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the EntityMap fragment with which the EntityMap is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2. -
-

6.32.3.3 DELETE

-

This method is associated to the operation “Delete EntityMap” and shall exhibit the behaviour defined by clause 5.14.3. The Entity identifier is the value of the resource URI variable “contextId”. Figure 6.32.3.3‑1 shows the delete entity interaction and Table 6.32.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.32.3.3-1: Delete and Reload @context interaction

-
-
-

Table 6.32.3.3-1: Delete EntityMap request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. -
-

6.33 Resource: info/sourceIdentity

-

6.33.1 Description

-

This resource represents identity information about the Context Source itself.

-

6.33.2 Resource definition

-

Resource URI:

-
-
    -
  • /info/sourceIdentity
    • -
-
-

6.33.3 Resource methods

-

6.33.3.1 GET

-

This method is associated to the operation “Retrieve Context Source Identity Information” and shall exhibit the behaviour defined by clause 5.15.1. Figure 6.33.3.1‑1 shows the Retrieve Context Source Identity Information interaction and Table 6.33.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.33.3.1-1: Retrieve Context Source Identity Information

-
-
-

Table 6.33.3.1-1: Retrieve Context Source Identity Information request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-ContextSourceIdentity -
-1 -
-200 No Content -
-A response body containing the JSON-LD representation of the Context Source Identity Information. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by Context Sources to indicate that retrieval of the Context Source information is unsupported see . -
-

6.34 Resource: entityMaps

-

6.34.1 Description

-

This resource represents the Entity maps in an NGSI-LD system.

-

6.34.2 Resource definition

-

Resource URI:

-
-
    -
  • /entityMaps/
    • -
-
-

6.34.3 Resource methods

-

6.34.3.1 GET

-

This method is associated to the operation “Create EntityMap for Query Entities” and shall exhibit the behaviour defined by clause 5.14.4, providing an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Create EntityMap for Query Entities” operations via POST is defined in clause 6.34.3.2. Figure 6.34.3.1‑1 shows the Create EntityMap for Query Entities interaction.

-
-

-
-
-

Figure 6.34.3.1-1: Create EntityMap for Query Entities interaction

-
-

The URL parameters that shall be supported by implementations are the same as those for Query Entities and can be found in Table 6.4.3.2‑1. Table 6.34.3.1‑1 describes the request body and possible responses.

-
-

Table 6.34.3.1‑1: Create EntityMap for Query Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Request Body

-
-

Data Type

-
-

Cardinality

-
-

Remarks

-
-N/A -
-N/A -
-
-
-Response Body -
-Data Type -
-Cardinality -
-Response Codes -
-Remarks -
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an“NGSILD-EntityMap”HTTP header that contains the resource URI of the EntityMap resource createdin the operation.

-
-EntityMap -
-1 -
-203 Non-Authoritative Information -
-

As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8.

-

The response shall also include a “Preference-Applied” HTTP header set to “ngsi-ld=<conformant-version>”.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returnedProblemDetailsstructure, thedetailattribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-501 Not Implemented -
-It is used by RegisteredContext Sourcesto indicate that the data format of the request is unsupported see clause 6.3.7. -
-

6.34.3.2 POST

-

This method is associated to the operation “Create EntityMap for Query Entities” and shall exhibit the behaviour defined by clause 5.14.4. Figure 6.34.3.2‑1 shows the operation interaction and Table 6.34.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.34.3.2-1: Create EntityMap for Query Entities via POST interaction

-
-
-

Table 6.34.3.2-1: Create EntityMap for Query Entities via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.35 Resource: temporal/entityMaps

-

6.35.1 Description

-

This resource is used for creating entityMaps based on temporal queries in an NGSI-LD system.

-

6.35.2 Resource definition

-

Resource URI:

-
-
    -
  • /temporal/entityMaps/
    • -
-
-

6.35.3 Resource methods

-

6.35.3.1 GET

-

This method is associated to the operation “Create EntityMap for Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.14.5, an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform “Create EntityMap for Query Temporal Evolution of Entities” operations via POST is defined in clause 6.35.3.2. Figure 6.35.3.1‑1 shows this interaction.

-
-

-
-
-

Figure 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities interaction

-
-

The URL parameters that shall be supported by implementations are the same as those for Query Temporal Evolution of Entities and can be found in Table 6.18.3.2‑1. Table 6.35.3.1‑1 describes the request body and possible responses.

-
-

Table 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.35.3.2 POST

-

This method is associated to the operation “Create EntityMap for Query Temporal Evolution of Entities” and shall exhibit the behaviour defined by clause 5.14.5. Figure 6.35.3.2‑1 shows the operation interaction and Table 6.35.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST interaction

-
-
-

Table 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Query

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the query to be performed.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-EntityMap -
-1 -
-201 Created -
-

A response body containing the entityMap with the identifiers of the Entities matching the query.

-

The HTTP response shall include an “NGSILD-EntityMap” HTTP header that contains the resource URI of the EntityMap resource created in the operation.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.36 Resource: snapshots

-

6.36.1 Description

-

This resource represents Snapshots available in an NGSI-LD system.

-

6.36.2 Resource definition

-

Resource URI:

-
-
    -
  • /snapshots/
    • -
-
-

6.36.3 Resource methods

-

6.36.3.1 POST

-

This method is associated to the operation “Create Snapshot” and shall exhibit the behaviour defined by clause 5.16.1. Figure 6.36.3.1‑1 shows the operation interaction and Table 6.36.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.36.3.1-1: Create Snapshot interaction

-
-
-

Table 6.35.3.2-1: Create Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents parameters for the snapshot to be created.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the created snapshot. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the a Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

6.36.3.2 DELETE

-

This method is associated to the operation “Purge Snapshots” and shall exhibit the behaviour defined by clause 5.16.7. Figure 6.36.3.2‑1 shows the Purge Snapshot interaction.

-
-

-
-
-

Figure 6.36.3.2-1: Purge Snapshots interaction

-
-

The URL parameters that shall be supported by implementations are those defined in Table 6.36.3.2‑1 and Table 6.36.3.2‑2 describes the request body and possible responses.

-
-

Table 6.36.3.2-1: Purge Snapshots URL parameters

-
- ------ - - - - - - - - - - - - - - - - -
NameData TypeCardinalityRemarks

{TAL}

-

q

{TAL}

-

String

{TAL}

-

1

{TAL}

-

Query as per clause 4.9, restricted to members of the Snapshot data type.

-
-

Table 6.36.3.2-2: Purge Snapshots request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-BatchOperationResult -
-1 -
-207 Multi-Status -
-If some or all of the Snapshots have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully deleted Snapshots, while the second array (errors) contains information about the error for each of the Snapshots that could not be deleted. There is no restriction as to the order of the Snapshots IDs in the arrays. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a filter not matching any Snapshots, see clause 6.3.2. -
-

6.37 Resource: snapshots/{snapshotId}

-

6.37.1 Description

-

This resource represents a snapshot in an NGSI-LD system.

-

6.37.2 Resource definition

-

Resource URI:

-
-
    -
  • /snapshots/{snapshotId}
    • -
-
-

Resource URI variables for this resource are defined in Table 6.37.2‑1.

-

Table 6.37.2‑1: URI variables

- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-snapshotId -
-Id (URI) of the Snapshot whose status is to be retrieved or updated, or the Snapshot to be deleted. -
-

6.37.3 Resource methods

-

6.37.3.1 GET

-

This method is associated to the operation “Retrieve Snapshot Status” and shall exhibit the behaviour defined by clause 5.16.3. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.1‑1 shows the Retrieve Snapshot Status interaction and Table 6.37.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.1-1: Retrieve Snapshot Status interaction

-
-
-

Table 6.37.3.1-1: Retrieve Snapshot Status request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-Response Body -
-Data Type -
-Cardinality -
-Response Codes -
-Remarks -
-Snapshot -
-1 -
-200 OK -
-

A response body containing the JSON-LD representation of the target Snapshot status.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-

ProblemDetails (see IETF RFC 7807 [10])

-
-

1

-
-

404 Not Found

-
-

It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

-
-

6.37.3.2 PATCH

-

This method is associated to the operation “Update Snapshot Status” and shall exhibit the behaviour defined by clause 5.16.4. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.2‑1 shows the Update Snapshot Status interaction and Table 6.37.3.2‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.2-1: Update Snapshot Status interaction

-
-
-

Table 6.37.3.2-1: Update Snapshot Status request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot Fragment

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents the Snapshot fragment with which the Snapshot status is to be updated.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-Snapshot -
-1 -
-200 OK -
-A response body containing the JSON-LD representation of the updated Snapshot status. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2. -
-

6.37.3.3 DELETE

-

This method is associated to the operation “Delete Snapshot” and shall exhibit the behaviour defined by . The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.37.3.3‑1 shows the Delete Snapshot interaction and Table 6.37.3.3‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.37.3.3-1: Delete Snapshot interaction

-
-
-

Table 6.37.3.3-1: Delete Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

N/A

-
-

N/A

-
-
-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-204 No Content -
-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a snapshot identifier not known to the system, see clause 6.3.2. -
-

6.38 Resource: snapshots/{snapshotId}/clone

-

6.38.1 Description

-

This resource enables the cloning of a snapshot in an NGSI-LD system.

-

6.38.2 Resource definition

-

Resource URI:

-
-
    -
  • /snapshots/{snapshotId}/clone
    • -
-
-

Resource URI variables for this resource are defined in Table 6.38.2‑1.

-

Table 6.38.2‑1: URI variables

- ---- - - - - - - - - - - - - -
-Name -
-Definition -
-snapshotId -
-Id (URI) of the Snapshot to be queried or deleted. -
-

6.38.3 Resource methods

-

6.38.3.1 POST

-

This method is associated to the operation “Clone Snapshot” and shall exhibit the behaviour defined by clause 5.16.2. The Snapshot identifier is the value of the resource URI variable “snapshotId”. Figure 6.38.3.1‑1 shows the Clone Snapshot interaction and Table 6.38.3.1‑1 describes the request body and possible responses.

-
-

-
-
-

Figure 6.38.3.1-1: Clone Snapshot interaction

-
-
-

Table 6.38.3.1-1: Clone Snapshot request body and possible responses

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Request Body -
-Data Type -
-Cardinality -
-Remarks -
-

Snapshot

-
-

1

-
-

Payload body in the request contains a JSON-LD object which represents parameters for the cloned snapshot.

-
-

Response Body

-
-

Data Type

-
-

Cardinality

-
-

Response Codes

-
-

Remarks

-
-N/A -
-N/A -
-201 Created -
-The HTTP response shall include a “Location” HTTP header that contains the relative path of the cloned snapshot. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-400 Bad Request -
-

It is used to indicate that the request or its content is incorrect, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-404 Not Found -
-It is used when a client provided a Snapshot identifier (URI) not known to the system, see clause 6.3.2. -
-ProblemDetails (see IETF RFC 7807 [10]) -
-1 -
-409 Conflict -
-

It is used to indicate that the Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2.

-

In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

-
-
- - - - - diff --git a/API/12-tabapi-mqtt-notification-binding.html b/API/12-tabapi-mqtt-notification-binding.html deleted file mode 100644 index 9601a1f111d84304400adf257c820cbb1ee8ec61..0000000000000000000000000000000000000000 --- a/API/12-tabapi-mqtt-notification-binding.html +++ /dev/null @@ -1,1670 +0,0 @@ - - - - - - - -7 API MQTT Notification Binding - - - - - - - - - - - - -
-

7 API MQTT Notification Binding

-

7.1 Introduction

-

This clause defines the optional support of the NGSI-LD API for sending notifications via the MQTT protocol [24] and [25]. The subscriptions are handled using the HTTP binding as described in clause 6, but instead of an HTTP endpoint, an MQTT endpoint is provided.

-

7.2 Notification behaviour

-

In case a subscription received via HTTP specifies an MQTT endpoint in the “notification.endpoint.uri” member of the subscription structure (defined by clauses 5.2.12, 5.2.14 and 5.2.15), and the MQTT notification binding is supported by the NGSI-LD implementation, notifications related to this subscription shall be sent via the MQTT protocol.

-

The syntax of an MQTT endpoint URI is mqtt[s]://[<username>][:<password>]@<host>[:<port>]/<topic>[/<subtopic>]* and follows an existing convention for representing an MQTT endpoint as a URI [i.19].

-

Username and password can be optionally specified as part of the endpoint URI. If the port is not explicitly specified, the default MQTT port is 1883 for MQTT over TCP and 8883 for mqtts, i.e. Secure MQTT over TLS. MQTT supports the structuring of topics as a hierarchy with any number of subtopic levels, which can be specified as part of the endpoint URI.

-

In MQTT, all non-protocol information has to be included into the MQTT message. This means that the actual notification as specified in clause 5.3.1, as well as additional information like MIME type, possibly the link to the @context and additional user-specified information, which in the HTTP case is provided as headers, has to be included into the MQTT message. The MQTT notification message shall be provided as a JSON Object with the two elements “metadata” and “body”. The actual notification, as specified in clause 5.3.1 is the value of “body”, whereas any additional information is provided as key-value pairs in “metadata”.

-

For the MQTT protocol, there are currently two versions supported, MQTTv3.1.1 [24] and MQTTv5.0 [25]. Also, there are three levels of quality of service:

-
-
    -
  • at most once (0);
    • -
  • at least once (1); and
    • -
  • exactly once (2).
    • -
-
-

These can be specified in the subscription as part of the optional array of KeyValuePair type (defined by clause 5.2.22) “notification.endpoint.notifierInfo”. The MQTT protocol parameters can be found in Table 7.2‑1. If not present, the given default value is used.

-
-

Table 7.2-1: Protocol parameters for MQTT in notifierInfo

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Key -
-Possible Values -
-Default -
-Source -
-Description -
-MQTT-QoS -
-0, 1, 2 -
-0 -
-

Subscription’s notification.endpoint

-

.notifierInfo

-
-MQTT Quality of service, at most once (0), at least once (1) and exactly once (2) -
-MQTT-Version -
-mqtt3.1.1, mqtt5.0 -
-mqtt5.0 -
-

Subscription’s notification.endpoint

-

.notifierInfo

-
-Version of MQTT protocol -
-

The MIME type associated with the notification shall be “application/json” by default. However, this can be changed to“application/ld+json” by means of the “endpoint.accept” member. The MIME type is specified as Content-Type in the “metadata” element of the MQTT message. If the target MIME type is “application/json” then the reference to the JSON-LD @context is provided as Link in the “metadata” element of the MQTT message, following the specification of the HTTP Link header as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available). Table 7.2‑2 lists these “receiver side” metadata parameters.

-
-

Table 7.2-2: Parameters for MQTT in “metadata”

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - -
-Key -
-Possible Values -
-Default -
-Source -
-Description -
-Content-Type -
-“application/json”, “application/ld+json” -
-“application/json” -
-

Subscription’s

-

notification

-

.endpoint.accept

-
-MIME type of the notification included in the “body” element of the MQTT message -
-Link -
-Same format as specified in JSON-LD specification [2], section 6.2 for the HTTP Link header -
-Link Header provided in Subscription -
-Contains the reference to the @context in case Content-Type is “application/json”. Example: <http://myhost.org/mycontext>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json” -
-
-

Additionally, if the optional array of KeyValuePair type (defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new entry for each member named “key” of the key, value pairs that make up the array shall be generated and added to the “metadata” element of the MQTT message. The content of each entry shall be set equal to the content of the corresponding “value” member of the KeyValuePair.

-
- - - - - diff --git a/API/13-annex-a-normative-ngsi-ld-identifier-considerations.html b/API/13-annex-a-normative-ngsi-ld-identifier-considerations.html deleted file mode 100644 index 8beda2766eec68965d1dbc1c8d694585d999176d..0000000000000000000000000000000000000000 --- a/API/13-annex-a-normative-ngsi-ld-identifier-considerations.html +++ /dev/null @@ -1,1541 +0,0 @@ - - - - - - - -Annex A (normative): NGSI-LD identifier considerations - - - - - - - - - - - - -
-

Annex A (normative): NGSI-LD identifier considerations

-

A.1 Introduction

-

The purpose of identifiers is to allow uniquely identifying NGSI-LD elements (Entities, Context Subscriptions or Context Source Registrations) within an NGSI-LD system. This annex is intended to clarify the different issues around the design of identifiers in NGSI-LD.

-

A.2 Entity identifiers

-

In order to enable the participation of NGSI-LD in linked data scenarios, all Entities are identified by URIs. If those URIs are expected to participate in external linked data relationships they should be dereferenceable.

-

It is noteworthy that the identifier from the point of view of NGSI-LD is different from the inherent identifier that a specific Entity may have. For instance, an NGSI-LD Entity of Type “Vehicle” may have a Property named licencePlateNumber, which it is actually a unique identifier from the point of view of the Entity domain, as it uniquely identifies the specific vehicle instance. However, from the point of view of the NGSI-LD system, it may have another identifier which might or might not include such licence plate number identifier.

-

A.3 NGSI-LD namespace

-

NGSI-LD defines a specific URN [9] namespace intended to help API users to design readable, clean and simple identifiers. As it is based on URNs, the usage of this identification approach is not recommended when dereferenceable URIs are needed (fully-fledged linked data scenarios).

-

The referred namespace is defined as follows (to be registered with IANA):

-
-
    -
  • namespace identifier: NID = “ngsi-ld”
    • -
  • namespace specific string: NSS = EntityTypeName “:” EntityIdentificationString
    • -
-
-

EntityTypeName shall be an Entity Type name which can be expanded to a URI as per the @context.

-

EntityIdentificationString shall be a string that allows uniquely identifying the subject Entity in combination with the other items being part of the NSS.

-
-
-

EXAMPLE:

-
-
-

urn:ngsi-ld:Person:28976543 .

-
-
-

It is recommended that applications use this URN namespace when applicable.

-

In general, the URN specification defines namespace equivalence in a case-insensitive manner, however it is assumed that context-broker implementations shall always use lowercase letters in namespaces where they have a choice in case, unless there is a strong reason otherwise. Restricting the namespace prefix to lower case urn:ngsi-ld: can improve caching and retrieval, since this ensures since alphabetic characters within the namespace specific string are always consistent.

-
- - - - - diff --git a/API/14-annex-b-normative-core-ngsi-ld-context-definition.html b/API/14-annex-b-normative-core-ngsi-ld-context-definition.html deleted file mode 100644 index eb16f3148fc220dabbc86322eaefc09fa8ab837e..0000000000000000000000000000000000000000 --- a/API/14-annex-b-normative-core-ngsi-ld-context-definition.html +++ /dev/null @@ -1,2029 +0,0 @@ - - - - - - - -Annex B (normative): Core NGSI-LD @context definition - - - - - - - - - - - - -
-

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

-

Below is the definition of the Core NGSI-LD @context which shall be supported by implementations.

-

Such definition has been tested using [i.7].

-
{
-  "@context": {
-    "@version": 1.1,
-    "@protected": true,
-    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
-    "geojson": "https://purl.org/geojson/vocab#",
-    "id": "@id",
-    "type": "@type",
-    "Attribute": "ngsi-ld:Attribute",
-    "AttributeList": "ngsi-ld:AttributeList",
-    "ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity",
-    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification",
-    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration",
-    "Date": "ngsi-ld:Date",
-    "DateTime": "ngsi-ld:DateTime",
-    "EntityType": "ngsi-ld:EntityType",
-    "EntityTypeInfo": "ngsi-ld:EntityTypeInfo",
-    "EntityTypeList": "ngsi-ld:EntityTypeList",
-    "ExecutionResultDetails": "ngsi-ld:ExecutionResultDetails",
-    "Feature": "geojson:Feature",
-    "FeatureCollection": "geojson:FeatureCollection",
-    "GeoProperty": "ngsi-ld:GeoProperty",
-    "GeometryCollection": "geojson:GeometryCollection",
-    "JsonProperty": "ngsi-ld:JsonProperty",
-    "LanguageProperty": "ngsi-ld:LanguageProperty",
-    "LineString": "geojson:LineString",
-    "ListProperty": "ngsi-ld:ListProperty",
-    "ListRelationship": "ngsi-ld:ListRelationship",
-    "MultiLineString": "geojson:MultiLineString",
-    "MultiPoint": "geojson:MultiPoint",
-    "MultiPolygon": "geojson:MultiPolygon",
-    "Notification": "ngsi-ld:Notification",
-    "Point": "geojson:Point",
-    "Polygon": "geojson:Polygon",
-    "Property": "ngsi-ld:Property",
-    "Relationship": "ngsi-ld:Relationship",
-    "Snapshot": "ngsi-ld:Snapshot",
-    "SnapshotNotification": "ngsi-ld:SnapshotNotification",
-    "Subscription": "ngsi-ld:Subscription",
-    "TemporalProperty": "ngsi-ld:TemporalProperty",
-    "Time": "ngsi-ld:Time",
-    "VocabProperty": "ngsi-ld:VocabProperty",
-    "accept": "ngsi-ld:accept",
-    "aggrParams": "ngsi-ld:aggrParams",
-    "aggrMethods": "ngsi-ld:aggrMethods",
-    "aggrPeriodDuration": "ngsi-ld:aggrPeriodDuration",
-    "attributeCount": "attributeCount",
-    "attributeDetails": "attributeDetails",
-    "attributeList": {
-      "@id": "ngsi-ld:attributeList",
-      "@type": "@vocab"
-    },
-    "attributeName": {
-      "@id": "ngsi-ld:attributeName",
-      "@type": "@vocab"
-    },
-    "attributeNames": {
-      "@id": "ngsi-ld:attributeNames",
-      "@type": "@vocab"
-    },
-    "attributeTypes": {
-      "@id": "ngsi-ld:attributeTypes",
-      "@type": "@vocab"
-    },
-    "attributes": {
-      "@id": "ngsi-ld:attributes",
-      "@type": "@vocab"
-    },
-    "attrs": "ngsi-ld:attrs",
-    "avg": {
-      "@id": "ngsi-ld:avg",
-      "@container": "@list"
-    },
-    "bbox": {
-      "@container": "@list",
-      "@id": "geojson:bbox"
-    },
-    "cacheDuration": "ngsi-ld:cacheDuration",
-    "collation": "ngsi-ld:collation",
-    "containedBy": "ngsi-ld:isContainedBy",
-    "contextSourceAlias": "ngsi-ld:contextSourceAlias",
-    "contextSourceExtras": {
-      "@id": "ngsi-ld:contextSourceExtras",
-      "@type": "@json"
-    },
-    "contextSourceInfo": "ngsi-ld:contextSourceInfo",
-    "contextSourceTimeAt": {
-      "@id": "ngsi-ld:contextSourceTimeAt",
-      "@type": "DateTime"
-    }, 
-    "contextSourceUptime": "ngsi-ld:contextSourceUptime",
-    "cooldown": "ngsi-ld:cooldown",
-    "coordinates": {
-      "@container": "@list",
-      "@id": "geojson:coordinates"
-    },
-    "createdAt": {
-      "@id": "ngsi-ld:createdAt",
-      "@type": "DateTime"
-    },
-    "csf": "ngsi-ld:csf",
-"data": "ngsi-ld:data",
-"dataset": {
-"@id": "ngsi-ld:hasDataset",
-      "@container": "@index"
-},
-"datasetId": {
-"@id": "ngsi-ld:datasetId",
-"@type": "@id"
-    },
-    "deletedAt": {
-      "@id": "ngsi-ld:deletedAt",
-      "@type": "DateTime"
-    }, 
-    "description": "http://purl.org/dc/terms/description",
-    "detail": "ngsi-ld:detail",
-    "distinctCount": {
-      "@id": "ngsi-ld:distinctCount",
-      "@container": "@list"
-    },
-    "endAt": {
-      "@id": "ngsi-ld:endAt",
-      "@type": "DateTime"
-    },
-    "endTimeAt": {
-      "@id": "ngsi-ld:endTimeAt",
-      "@type": "DateTime"
-    },
-    "endpoint": "ngsi-ld:endpoint",
-    "entities": "ngsi-ld:entities",
-    "entity": "ngsi-ld:entity",
-    "entityCount": "ngsi-ld:entityCount",
-    "entityId": {
-      "@id": "ngsi-ld:entityId",
-      "@type": "@id"
-    },
-    "entityList": {
-      "@id": "ngsi-ld:entityList",
-      "@container": "@list"
-    },
-    "entityMap": "ngsi-ld:hasEntityMap",
-    "error": "ngsi-ld:error",
-    "errors": "ngsi-ld:errors",
-    "expandValues": "ngsi-ld:expandValues",
-    "expiresAt": {
-      "@id": "ngsi-ld:expiresAt",
-      "@type": "DateTime"
-    },
-    "features": {
-      "@container": "@set",
-      "@id": "geojson:features"
-    },
-    "format": "ngsi-ld:format",
-    "geoQ": "ngsi-ld:geoQ",
-    "geometry": "geojson:geometry",
-    "geoproperty": "ngsi-ld:geoproperty",
-    "georel": "ngsi-ld:georel",
-    "idPattern": "ngsi-ld:idPattern",
-    "information": "ngsi-ld:information",
-    "instanceId": {
-      "@id": "ngsi-ld:instanceId",
-      "@type": "@id"
-    },
-    "isActive": "ngsi-ld:isActive",
-    "join": "ngsi-ld:join",
-    "joinLevel": "ngsi-ld:hasJoinLevel",
-    "json": {
-      "@id": "ngsi-ld:hasJSON", "@type": "@json"
-    },
-    "jsonKeys": "ngsi-ld:jsonKeys",
-    "jsons": {
-      "@id": "ngsi-ld:jsons",
-      "@container": "@list"
-    },
-    "key": "ngsi-ld:hasKey",
-    "lang": "ngsi-ld:lang",
-    "languageMap": {
-      "@id": "ngsi-ld:hasLanguageMap",
-      "@container": "@language"
-    },
-    "languageMaps": {
-      "@id": "ngsi-ld:hasLanguageMaps",
-      "@container": "@list"
-    },
-    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
-    "lastFailure": {
-      "@id": "ngsi-ld:lastFailure",
-      "@type": "DateTime"
-    },
-    "lastNotification": {
-      "@id": "ngsi-ld:lastNotification",
-      "@type": "DateTime"
-    },
-    "lastSuccess": {
-      "@id": "ngsi-ld:lastSuccess",
-      "@type": "DateTime"
-    },
-    "lastUsedAt": {
-      "@id": "ngsi-ld:lastUsedAt",
-      "@type": "DateTime"
-    },
-    "linkedMaps": "ngsi-ld:linkedMaps",
-    "localOnly": "ngsi-ld:localOnly",
-    "location": "ngsi-ld:location",
-    "management": "ngsi-ld:management",
-    "managementInterval": "ngsi-ld:managementInterval",
-    "max": {
-      "@id": "ngsi-ld:max",
-      "@container": "@list"
-    },
-    "min": {
-      "@id": "ngsi-ld:min",
-      "@container": "@list"
-    },
-    "mode": "ngsi-ld:mode",
-    "modifiedAt": {
-      "@id": "ngsi-ld:modifiedAt",
-      "@type": "DateTime"
-    },
-    "ngsildproof": {
-      "@id": "ngsi-ld:ngsildproof",
-      "@context": [{
-        "entityIdSealed": "ngsi-ld:entityIdSealed",
-        "entityTypeSealed": {
-          "@id": "ngsi-ld:entityTypeSealed",
-          "@type": "@vocab"
-        }
-      },
-      "https://w3id.org/security/data-integrity/v2"
-      ]
-    },
-    "notification": "ngsi-ld:notification",
-    "notificationTrigger": "ngsi-ld:notificationTrigger",
-    "notifiedAt": {
-      "@id": "ngsi-ld:notifiedAt",
-      "@type": "DateTime"
-    },
-    "notifierInfo": "ngsi-ld:notifierInfo",
-    "notUpdated": "ngsi-ld:notUpdated",
-    "object": {
-      "@id": "ngsi-ld:hasObject",
-      "@type": "@id"
-    },
-    "objectList": {
-      "@id": "ngsi-ld:hasObjectList",
-      "@container": "@list"
-    },
-    "objectLists": {
-      "@id": "ngsi-ld:hasObjectLists",
-      "@container": "@list"
-    },
-    "objects": {
-      "@id": "ngsi-ld:hasObjects",
-      "@container": "@list"
-    },
-    "objectType": {
-      "@id": "ngsi-ld:hasObjectType",
-      "@type": "@vocab"
-    },
-    "observationInterval": "ngsi-ld:observationInterval",
-    "observationSpace": "ngsi-ld:observationSpace",
-    "observedAt": {
-      "@id": "ngsi-ld:observedAt",
-      "@type": "DateTime"
-    },
-    "omit": "ngsi-ld:omit",
-    "operations": "ngsi-ld:operations",
-    "operationSpace": "ngsi-ld:operationSpace",
-    "orderBy": {
-      "@container": "@list",
-      "@id": " ngsi-ld:orderBy "
-    },
-    "ordering": "ngsi-ld:ordering",
-    "pick": "ngsi-ld:pick",
-    "previousJson": {
-      "@id": "ngsi-ld:hasPreviousJson",
-      "@type": "@json"
-    },
-    "previousLanguageMap": {
-      "@id": "ngsi-ld:hasPreviousLanguageMap",
-      "@container": "@language"
-    },
-    "previousObject": {
-      "@id": "ngsi-ld:hasPreviousObject",
-      "@type": "@id"
-    },
-    "previousObjectList": {
-      "@id": "ngsi-ld:hasPreviousObjectList",
-      "@container": "@list"
-    },
-    "previousValue": "ngsi-ld:hasPreviousValue",
-    "previousValueList": {
-      "@id": "ngsi-ld:hasPreviousValueList",
-      "@container": "@list"
-    },
-    "previousVocab": {
-      "@id": "ngsi-ld:hasPreviousVocab",
-      "@type": "@vocab"
-    },
-    "problemDetails": {
-      "@id": "ngsi-ld:problemDetails",
-      "@type": "@json"
-    },
-    "properties": "geojson:properties",
-    "propertyNames": {
-      "@id": "ngsi-ld:propertyNames",
-      "@type": "@vocab"
-    },
-    "q": "ngsi-ld:q",
-    "reason": "ngsi-ld:reason",
-    "receiverInfo": "ngsi-ld:receiverInfo",
-    "refreshRate": "ngsi-ld:refreshRate",
-    "registrationId": "ngsi-ld:registrationId",
-    "registrationName": "ngsi-ld:registrationName",
-    "relationshipNames": {
-      "@id": "ngsi-ld:relationshipNames",
-      "@type": "@vocab"
-},
-    "resultStatus": "ngsi-ld:resultStatus",
-"scope": "ngsi-ld:scope",
-"scopeQ": "ngsi-ld:scopeQ",
-"showChanges": "ngsi-ld:showChanges",
-    "snapshotId": "ngsi-ld:snapshotId",
-    "snapshotLifetime": "ngsi-ld:snapshotLifetime",
-    "snapshotPriority": "ngsi-ld:snapshotPriority",
-    "snapshotQueries": {
-      "ngsi-ld:snapshotQueries",
-      "@container": "@list"
-    },
-    "snapshotQueriesDetails": {
-      "ngsi-ld:snapshotQueriesDetails",
-      "@container": "@list"
-    },
-    "snapshotStatus": "ngsi-ld:snapshotStatus,
-    "snapshotTemporalQueries": {
-      "ngsi-ld:snapshotTemporalQueries",
-      "@container": "@list"
-    },
-    "snapshotTemporalQueriesDetails": {
-      "ngsi-ld:snapshotTemporalQueriesDetails",
-      "@container": "@list"
-    },
-    "startAt": {
-      "@id": "ngsi-ld:startAt",
-      "@type": "DateTime"
-    },
-    "status": "ngsi-ld:status",
-    "stddev": {
-      "@id": "ngsi-ld:stddev",
-      "@container": "@list"
-    },
-    "subscriptionId": {
-      "@id": "ngsi-ld:subscriptionId",
-      "@type": "@id"
-    },
-    "subscriptionName": "ngsi-ld:subscriptionName",
-    "success": {
-      "@id": "ngsi-ld:success",
-      "@type": "@id"
-    },
-    "sum": {
-      "@id": "ngsi-ld:sum",
-      "@container": "@list"
-    },
-    "sumsq": {
-      "@id": "ngsi-ld:sumsq",
-      "@container": "@list"
-    },
-    "sysAttrs": "ngsi-ld:sysAttrs",
-    "temporalQ": "ngsi-ld:temporalQ",
-    "tenant": {
-      "@id": "ngsi-ld:tenant",
-      "@type": "@id"
-    },
-    "throttling": "ngsi-ld:throttling",
-    "timeAt": {
-      "@id": "ngsi-ld:timeAt",
-      "@type": "DateTime"
-    },
-    "timeInterval": "ngsi-ld:timeInterval",
-    "timeout": "ngsi-ld:timeout",
-    "timeproperty": "ngsi-ld:timeproperty",
-    "timerel": "ngsi-ld:timerel",
-    "timesFailed": "ngsi-ld:timesFailed",
-    "timesSent": "ngsi-ld:timesSent",
-    "title": "http://purl.org/dc/terms/title",
-    "totalCount": {
-      "@id": "ngsi-ld:totalCount",
-      "@container": "@list"
-    },
-    "triggerReason": "ngsi-ld:triggerReason",
-    "typeList": {
-      "@id": "ngsi-ld:typeList",
-      "@type": "@vocab"
-    },
-    "typeName": {
-      "@id": "ngsi-ld:typeName",
-      "@type": "@vocab"
-    },
-    "typeNames": {
-      "@id": "ngsi-ld:typeNames",
-      "@type": "@vocab"
-    },
-    "unchanged": "ngsi-ld:unchanged",
-    "unitCode": "ngsi-ld:unitCode",
-    "updated": "ngsi-ld:updated",
-    "uri": "ngsi-ld:uri",
-    "value": "ngsi-ld:hasValue",
-    "valueList": {
-      "@id": "ngsi-ld:hasValueList",
-      "@container": "@list"
-    },
-    "valueLists": {
-      "@id": "ngsi-ld:hasValueLists",
-      "@container": "@list"
-    },
-    "values": {
-      "@id": "ngsi-ld:hasValues",
-      "@container": "@list"
-    },
-    "valueType": {
-      "@id": "ngsi-ld:hasValueType",
-      "@type": "@vocab"
-    },
-    "vocab": {
-      "@id": "ngsi-ld:hasVocab",
-      "@type": "@vocab"
-    },
-    "vocabs": {
-      "@id": "ngsi-ld:hasVocabs",
-      "@container": "@list"
-    },
-    "watchedAttributes": {
-      "@id": "ngsi-ld:watchedAttributes",
-      "@type": "@vocab"
-    },
-    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/"
-  }
-}
-
-
-

NOTE:

-
-
-

Implementers can take advantage of prefixed terms, i.e. in the form ngsi-ld:term, to provide a terser representation of the Core @context .

-
-
-
- - - - - diff --git a/API/15-annex-c-informative-examples-of-using-the-api.html b/API/15-annex-c-informative-examples-of-using-the-api.html deleted file mode 100644 index 00e007bdb75e706e0ce728460e68d65afe48b6f5..0000000000000000000000000000000000000000 --- a/API/15-annex-c-informative-examples-of-using-the-api.html +++ /dev/null @@ -1,4366 +0,0 @@ - - - - - - - -Annex C (informative): Examples of using the API - - - - - - - - - - - - -
-

Annex C (informative): Examples of using the API

-

C.1 Introduction

-

This annex is informative and is intended to show in action the JSON-LD representation defined by NGSI-LD.

-

JSON representations of the examples shown in this annex can be found at [i.15].

-

C.2 Entity Representation

-

C.2.1 Property Graph

-

Figure C.2.1‑1 shows a diagram representing a property graph to be used for the examples discussed in this clause.

-
-

-
-
-

Figure C.2.1-1: Reference example

-
-

As per the algorithms described above and as per the rules for generating the JSON-LD representation of NGSI-LD entities the above graph will result in the following JSON-LD representations. The syntax has been checked using the JSON-LD Playground tool [i.5].

-

C.2.2 Vehicle Entity

-

Normalized Representation

-

The normalized representation is a lossless representation of an Entity, where every Property is defined by a type and a value and every Relationship is defined by a type and an object.

-

Below there is a representation of an Entity of Type “Vehicle”. It can be observed that the @context is composed of different parts, namely the Core @context and several vocabulary-specific @contexts.

-

It is noteworthy that the @context corresponding to the Parking domain is included as it is referenced through the isParked Relationship.

-

Normalized Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned in an expanded format. Attributes of type“Relationship”are returned with an additional entity sub-Attribute, which holds the normalized Linked Entity data corresponding to the Relationship’s target object URI. Attributes of type“ListRelationship” are returned with an additional entityList sub-Attribute which in turn holds an ordered array of the normalized Linked Entities corresponding to the target “objectList” URIs.

-

Normalized Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of normalized Entities is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional normalized Linked Entity holding data corresponding to the Relationship’s target object URI is appended to the array. For Attributes of type “ListRelationship”, an array of normalized Linked Entities is appended, which hold the data corresponding to each of the target URIs found within its objectList.

-

[

-

Normalized Representation when Language Filter is used

-

When the Language Filter (see clause 4.15) is used, Properties of type “LanguageProperty” are returned as type “Property”, and their languageMaps are reduced to simple strings. For example if the language filter lang=fr is specified, only the value for French language is present.

-
{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-        "type": "Relationship",
-    "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-    "type": "Relationship",
-    "objectType": "OffStreetParking",
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "entity": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "value": "Top Parking",
-    "type": "Property"
-    },
-    "operatedBy": {
-    "object" "urn:ngsi-ld:Company:BigParkingCorp",
-    "type": "Relationship"
-    },
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person", 
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "entity": [
-    {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": {
-        "value": "Alice",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": {
-        "value": "Bob",
-        "type": "Property"
-    }
-    }
-    ]
-},
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ],
-    "entityList": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": {
-        "value": "Antwerp",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": {
-        "value": "Rotterdam",
-        "type": "Property"
-    }
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": {
-        "value": "Amsterdam",
-        "type": "Property"
-    }
-    }
-    ]
-},
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-    {
-        "id": "urn:ngsi-ld:Vehicle:A4567",
-        "type": "Vehicle",
-        "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "LanguageProperty",
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt
-    } 
-    },
-    "isParked": {
-        "type": "Relationship",
-    "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-        "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-    "tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120, [6],
-        "valueType": "Integer"
-    "unitCode": "MMT"
-    },
-    "passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-    "route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-        {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-        {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "value": "Top Parking",
-    "type": "Property"
-    },
-    "operatedBy": {
-    "object" "urn:ngsi-ld:Company:BigParkingCorp",
-    "type": "Relationship"
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": {
-    "value": "Alice",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": {
-    "value": "Bob",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": {
-    "value": "Antwerp",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": {
-    "value": "Rotterdam",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": {
-    "value": "Amsterdam",
-    "type": "Property"
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    }
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": {
-        "type": "Property",
-    "value": "Mercedes"
-    },
-    "street": {
-    "type": "Property",
-    "value": "Grand Place",
-    "lang": "fr"
-    },
-    "isParked": {
-        "type": "Relationship",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-        "type": "VocabProperty",
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "type": "ListProperty",
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "type": "Relationship",
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "type": "ListRelationship",
-    "objectType": "City",
-    "objectList": [
-    {"object": "urn:ngsi-ld:City:Antwerp"},
-    {"object": "urn:ngsi-ld:City:Rotterdam"}
-    {"object": "urn:ngsi-ld:City:Amsterdam"}
-    ]
-},
-"@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-

Concise Representation

-

The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute type members are omitted and the following rules are applied:

-
-
    -
  • Every Property without further sub-attributes is represented directly by the Property value only.
    • -
  • Every Property that includes further sub-attributes is represented by a value key-value pair.
    • -
  • Every GeoProperty without further sub-attributes is represented by the GeoProperty’s GeoJSON representation only.
    • -
  • Every GeoProperty that includes further sub-attributes is represented by a value key-value pair.
    • -
  • Every LanguageProperty is represented by a languageMap key-value pair.
    • -
  • Every ListProperty is represented directly by the array of Property values.
    • -
  • Every JsonProperty is represented by a json the value of which is raw JSON which is not available for JSON-LD representation.
    • -
  • Every VocabProperty is represented by a vocab the value of which is a compacted URI.
    • -
  • Every Relationship is represented by an object key-value pair.
    • -
  • Every ListRelationship is represented by an array of URIs.
    • -
-
-

Concise Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned in an expanded format. The concise Linked Entity data corresponding to the Relationship’s target object URI is returned within an entity sub-Attribute. Attributes of type “ListRelationship”are returned within an entityList sub-Attribute which in turn holds an ordered array of the Linked Entities in the concise format corresponding to each of the targetobjectList URIs.

-
    "name": " Antwerp"
-    "name": "Rotterdam
-    "name": "Amsterdam"
-

Concise Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of concise Entities is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional concise Linked Entity holding data corresponding to the Relationship’s target object URI is appended to the response. For Attributes of type “ListRelationship”, an array of concise Linked Entities is appended to the response which hold the data corresponding to each of the target URIs found within its objectList.

-

[

-

Concise representation when Language Filter is used

-

The rules apply as defined in the previous examples. For example if the language filter lang=fr is specified.

-

Simplified Representation

-

The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

Simplified Representation when inline Linked Entity retrieval is used

-

When inline Linked Entity retrieval (see clause 4.5.23.2) is specified, any Relationships which target Entities stored locally or include an objectType Attribute are returned as a JSON object holding key-value pairs corresponding to the data from the Relationship’s target object URI in simplified format. Attributes of type “ListRelationship”are returned as array of JSON objects each holding key-value pairs corresponding to the data obtained from the target objectList URIs.

-

Simplified Representation when flattened Linked Entity retrieval is used

-

When flattened Linked Entity retrieval (see clause 4.5.23.3) is specified, an array of JSON Objects is returned. Whenever a Relationship Attribute targets an Entity stored locally or includes an objectType, an additional JSON Object of key-value pairs holding data corresponding to the Relationship’s target object URI is appended to the response. For Attributes of type “ListRelationship”, an array of JSON Objects each holding key-value pairs corresponding to the data obtained from the target objectList URIs is appended to the response.

-
[
-    "name": " Antwerp"
-    "name": "Rotterdam
-    "name": "Amsterdam"
-}
-

Simplified Representation of Natural Language Attributes

-

The simplified natural language representation is a collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph, and where languageMaps are reduced to simple string properties. For example if the language filter lang=fr is specified.

-

Multiple attribute example

-

Below is an example, where the speed of the car is provided by two different sources. As both may be relevant at the same time, there are two individual attribute instances for speed; each is identified by a datasetId and both instances are represented in an array. The datasetId enables individually creating, updating and deleting a particular instance without affecting the instance from another source.

-

Simplified Representation of a multi-attribute

-

The simplified representation is a collapsed, lossy representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

C.2.3 Parking Entity

-

Normalized Representation

-

The normalized representation is a lossless representation of an Entity, where every Property is defined by a type and a value and every Relationship is defined by a type and an object.

-

Below there is a representation of an Entity of Type “OffStreetParking”. It can be observed that the @context is composed of two different elements, the Core one and the vocabulary-specific one.

-
{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-        "languageMap": {
-            "fr": "Grand Place",
-            "nl": "Grote Markt"
-        } 
-    },
-    "isParked": {
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer"
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ]
-    },
-"@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-        "languageMap": {
-            "fr": "Grand Place",
-            "nl": "Grote Markt"
-        } 
-    },
-    "isParked": {
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-        "entity": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Top Parking",
-    "operatedBy": {
-    "object": "urn:ngsi-ld:Company:BigParkingCorp"
-      }
-    },
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "entity": [
-    {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": "Alice"
-        },
-        {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": "Bob"
-        }
-]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ],
-    "entityList": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    }
-    ]
-},
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-}
-    {
-        "id": "urn:ngsi-ld:Vehicle:A4567",
-        "type": "Vehicle",
-        "brandName": "Mercedes",
-        "street": {
-            "languageMap": {
-                "fr": "Grand Place",
-                "nl": "Grote Markt"
-            } 
-        },
-        "isParked": { 
-    "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "objectType": "OffStreetParking",
-            "observedAt": "2017-07-29T12:00:04Z",
-            "providedBy": {
-                "object": "urn:ngsi-ld:Person:Bob"
-            } 
-        },
-    "category": {
-    "vocab": "non-commercial"
-    },
-    "tyreTreadDepths": {
-    "valueList": [300, 300, 120, [6],
-        "valueType": "Integer",
-    "unitCode": "MMT"
-    },
- "passengers": {
-    "objectType": "Person",
-    "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-    },
-    "route": {
-    "objectType": "City",
-    "objectList": [
-        "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-        "urn:ngsi-ld:City:Amsterdam"
-    ]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Top Parking",
-    "operatedBy": {
-    "object" "urn:ngsi-ld:Company:BigParkingCorp",
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Alice",
-    "type": "Person",
-    "name": "Alice",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": " urn:ngsi-ld:Person:Bob",
-    "type": "Person",
-    "name": "Bob",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-  "name": " Antwerp",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": "Rotterdam",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": "Amsterdam",
-    "@context": [
-        "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-        "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" 
-    ]
-    }
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes"
-    },
-    "street": {
-    "value": "Grand Place",
-    "lang": "fr"
-    },
-    "isParked": {
-  "objectType": "OffStreetParking",
-        "object": "urn:ngsi-ld:OffStreetParking:Downtown1",
-        "observedAt": "2017-07-29T12:00:04Z",
-        "providedBy": {
-            "object": "urn:ngsi-ld:Person:Bob"
-        } 
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": {
-    "valueList": [300, 300, 120, [6],
-    "valueType": "Integer",
-    "unitCode": "MMT"
-},
-"passengers": {
-    "objectType": "Person",
-   "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"]
-},
-"route": {
-    "objectType": "City",
-    "objectList": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ]
-},
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    }
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120, [6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-"route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    },
-    "isParked": {
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": " OffStreetParking",  
-    "name": "Top Parking",
-    "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp"
-    },
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120, [6],
-"passengers": [
- {
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person", 
-    "name": "Alice"
-    },
-    {
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person", 
-    "name": "Bob"
-    }
-],
-    "route": [
-    {
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-    "name": " Antwerp"
-        },
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    "name": "Rotterdam
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-    "name": "Amsterdam"
-        }
-    ],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": {
-    "languageMap": {
-    "fr": "Grand Place",
-    "nl": "Grote Markt" 
-    }
-    }
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120, [6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-    "route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-    ],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-},
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": " OffStreetParking",  
-    "name": "Top Parking",
-    "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp"
-},
-{
-    "id": "urn:ngsi-ld:Person:Alice",
-    "type": "Person", 
-    "name": "Alice"
-}
-{
-    "id": "urn:ngsi-ld:Person:Bob",
-    "type": "Person", 
-    "name": "Bob"
-},
-{
-    "id": "urn:ngsi-ld:City:Antwerp",
-    "type": "City",
-},
-    {
-    "id": "urn:ngsi-ld:City:Rotterdam",
-    "type": "City",
-    },
-    {
-    "id": "urn:ngsi-ld:City:Amsterdam",
-    "type": "City",
-]
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "street": "Grand Place",
-    "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "category": {
-    "vocab": "non-commercial"
-    },
-"tyreTreadDepths": [300, 300, 120, [6],
-"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"],
-"route": [
-    "urn:ngsi-ld:City:Antwerp",
-    "urn:ngsi-ld:City:Rotterdam",
-    "urn:ngsi-ld:City:Amsterdam"
-],
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "speed": [{
-        "type": "Property",
-    "value": 55,
-    "source": {
-            "type": "Property",
-    "value": "Speedometer"
-    },
-    "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
-    },
-    {
-        "type": "Property",
-    "value": 54.5,
-    "source": {
-            "type": "Property",
-    "value": "GPS"
-    },
-    "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
-    }],
-    "@context": [
-        {
-    "Vehicle": "http://example.org/Vehicle",
-    "speed": "http://example.org/speed",
-        "source": "http://example.org/hasSource"
-        },
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "speed": {
-    "dataset": {
-    "urn:ngsi-ld:Property:speedometerA4567-speed": 55,
-    "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5
-    }
-    },
-    "@context": [
-        {
-    "Vehicle": "http://example.org/Vehicle",
-    "speed": "http://example.org/speed"
-        },
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": {
-    "type": "Property",
-        "value": "Downtown One"
-    },
-    "availableSpotNumber": {
-        "type": "Property",
-        "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z",
-        "reliability": {
-        "type": "Property",
-        "value": 0.7
-        },
-        "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-        }
-    },
-    "totalSpotNumber": {
-        "type": "Property",
-        "value": 200
-    },
-    "location": {
-    "type": "GeoProperty",
-    "value": {
-    "type": "Point",
-    "coordinates": [-8.5, 41.2]
-    }
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-

Concise Representation

-

The concise representation is a terser, lossless form of the normalized representation, where redundant Attribute type members are omitted and the following rules are applied:

-
-
    -
  • Every Property without further sub-attributes is represented by the Property value only.
    • -
  • Every Property that includes further sub-attributes is represented by a value key-value pair.
    • -
  • Every GeoProperty without further sub-attributes is represented by the GeoProperty’s GeoJSON representation only.
    • -
  • Every GeoProperty that includes further sub-attributes is represented by a value key-value pair.
    • -
  • Every LanguageProperty is defined by a languageMap key-value pair.
    • -
  • Every VocabProperty is represented by a vocab the value of which is a compacted URI.
    • -
  • Every Relationship is defined by an object key-value pair.
    • -
-
-

Simplified representation

-

The Simplified Representation (also known as “keyValues”) is a lossy, collapsed representation of an Entity, which focuses on Property Values and Relationship objects present at the first level of the graph only.

-

Normalized GeoJSON Representation

-

The normalized GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object as follows:

-

The GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations.

-

Concise GeoJSON Representation

-

The concise GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object as follows:

-

The concise GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations in concise GeoJSON format.

-

Simplified GeoJSON Representation

-

The simplified GeoJSON representation of a single Entity is defined as a single GeoJSON Feature object where the properties represent a collapsed representation of the Entity, which focuses on Property Values and Relationship objects present at the first level of the graph.

-

The simplified GeoJSON representation of multiple Entities is defined as a GeoJSON FeatureCollection object containing an array of GeoJSON features corresponding to the individual Entity representations in simplified GeoJSON format.

-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffStreetParking",
-  "name": "Downtown One",
-  "availableSpotNumber": {
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z",
-    "reliability": 0.7,
-    "providedBy": {
-      "object": "urn:ngsi-ld:Camera:C1"
-    }
-  },
-  "totalSpotNumber": 200,
-  "location": {
-    "type": "Point",
-    "coordinates": [
-      -8.5,
-      41.2
-    ]
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": 121,
-    "totalSpotNumber": 200,
-    "location": {
-    "type": "Point",
-    "coordinates": [-8.5, 41.2]
-    },
-    "@context": [
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": {
-      "type": "Property",
-      "value": "Downtown One"
-    },
-    "availableSpotNumber": {
-      "type": "Property",
-      "value": 121,
-      "observedAt": "2017-07-29T12:05:02Z",
-      "reliability": {
-        "type": "Property",
-        "value": 0.7
-      },
-      "providedBy": {
-        "type": "Relationship",
-        "object": "urn:ngsi-ld:Camera:C1"
-      }
-    },
-    "location": {
-    "type": "GeoProperty",
-    "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-    }
-    },
-    "totalSpotNumber": {
-      "type": "Property",
-      "value": 200
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/parking.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.5, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": {
-          "type": "Property",
-          "value": "Downtown One"
-        },
-        "availableSpotNumber": {
-          "type": "Property",
-          "value": 121,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": {
-            "type": "Property",
-            "value": 0.7
-          },
-          "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-          }
-        },
-        "totalSpotNumber": {
-          "type": "Property",
-          "value": 200
-        },
-    "location": {
-      "type": "GeoProperty",
-      "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-      }
-    }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.51, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": {
-          "type": "Property",
-          "value": "Downtown Two"
-        },
-        "availableSpotNumber": {
-          "type": "Property",
-          "value": 99,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": {
-            "type": "Property",
-            "value": 0.8
-          },
-          "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C2"
-          }
-        },
-        "totalSpotNumber": {
-          "type": "Property",
-          "value": 100
-        },
-    "location": {
-      "type": "GeoProperty",
-      "value": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-      }
-    }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [
-      -8.51,
-      41.1
-    ]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": {
-      "value": 121,
-      "observedAt": "2017-07-29T12:05:02Z",
-      "reliability": 0.7,
-      "providedBy": {
-        "object": "urn:ngsi-ld:Camera:C1"
-      }
-    },
-    "location": {
-      "type": "Point",
-      "coordinates": [
-        -8.51,
-        41.1
-      ]
-    },
-    "totalSpotNumber": 200,
-    "@context": [
-      "http://example.org/ngsi-ld/latest/parking.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [
-          -8.5,
-          41.1
-        ]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown One",
-        "availableSpotNumber": {
-          "value": 121,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": 0.7,
-          "providedBy": {
-            "object": "urn:ngsi-ld:Camera:C1"
-          }
-        },
-        "totalSpotNumber": 200,
-        "location": {
-          "type": "Point",
-          "coordinates": [
-            -8.51,
-            41.1
-          ]
-        }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [
-          -8.51,
-          41.1
-        ]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown Two",
-        "availableSpotNumber": {
-          "value": 99,
-          "observedAt": "2017-07-29T12:05:02Z",
-          "reliability": 0.8,
-          "providedBy": {
-            "object": "urn:ngsi-ld:Camera:C2"
-          }
-        },
-        "totalSpotNumber": 100,
-        "location": {
-          "type": "Point",
-          "coordinates": [
-            -8.51,
-            41.1
-          ]
-        }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:offstreetparking:Downtown1",
-  "type": "Feature",
-  "geometry": {
-    "type": "Point",
-    "coordinates": [-8.51, 41.1]
-  },
-  "properties": {
-    "type": "OffStreetParking",
-    "name": "Downtown One",
-    "availableSpotNumber": 121,
-    "totalSpotNumber": 200,
-    "location": {
-      "type": "Point",
-      "coordinates": [-8.51, 41.1]
-    }
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.5, 41.2]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown One",
-        "availableSpotNumber": 121,
-        "totalSpotNumber": 200,
-        "location": {
-       "type": "Point",
-       "coordinates": [-8.5, 41.2]
-        }
-      }
-    },
-    {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown2",
-      "type": "Feature",
-      "geometry": {
-        "type": "Point",
-        "coordinates": [-8.51, 41.1]
-      },
-      "properties": {
-        "type": "OffStreetParking",
-        "name": "Downtown Two",
-        "availableSpotNumber": 99,
-        "totalSpotNumber": 100,
-        "location": {
-       "type": "Point",
-       "coordinates": [-8.51, 41.1]
-        }
-      }
-    }
-  ],
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}  
-

C.2.4 @context

-

The disposition of the @context can be as an inline JSON object, as a dereferenceable URI or as a (multiple) combination of both. In the examples above the @context is provided through several dereferenceable URIs. The resulting @context (obtained by merging the content of the resource referenced by the referred URIs) is shown below.

-
-
-

NOTE 1:

-
-
-

For brevity reasons the @context does not contain the API terms defined by clause 5.2 .

-
-
-
-
-

NOTE 2:

-
-
-

Some extra terms are defined because they will be used in examples later presented.

-
-
-

C.3 Context Source Registration

-

Below there is an example representation of a Context Source Registration. It makes use of the @context formerly described.

-

The Registration is referring to a Temporal Context Source capable of providing temporal information from Entities of type “Vehicle” and “OffStreetParking”, meeting certain id requirements. More concretely, it can only provide the referenced Properties and Relationships. Temporal information is provided for the given managementInterval, i.e. related to createdAt and modifiedAt Temporal Properties. The managementInterval is specified as an open interval, so only a starting point is given. In addition, the Registration example covers a particular geographical area.

-

C.4 Context Subscription

-

Below there is an example of a Context Subscription. It makes use of the @context formerly described.

-
{
-    "id": "@id",
-    "type": "@type",
-    "Property": "https://uri.etsi.org/ngsi-ld/Property",
-    "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship",
-    "value": "https://uri.etsi.org/ngsi-ld/hasValue",
-    "object": {
-    "@type": "@id",
-    "@id": "https://uri.etsi.org/ngsi-ld/hasObject"
-    },
-    "observedAt": {
-    "@type": "https://uri.etsi.org/ngsi-ld/DateTime",
-    "@id": "https://uri.etsi.org/ngsi-ld/observedAt"
-},
-    "datasetId": {
-        "@id": "https://uri.etsi.org/ngsi-ld/datasetId",
-        "@type":"@id"
-    },
-    "location": "https://uri.etsi.org/ngsi-ld/location",
-"GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty",
-    "Vehicle": "http://example.org/vehicle/Vehicle",
-    "street": "http://example.org/vehicle/street",
- "brandName": "http://example.org/vehicle/brandName",
- "category": "http://example.org/vehicle/category",
-    "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths",
- "passengers": "http://example.org/vehicle/passengers",
- "speed": "http://example.org/vehicle/speed",
-    "isParked": {
-    "@type": "@id",
-    "@id": "http://example.org/common/isParked"
-    },
-    "OffStreetParking": "http://example.org/parking/OffStreetParking",
-    "availableSpotNumber": "http://example.org/parking/availableSpotNumber",
-    "totalSpotNumber": "http://example.org/parking/totalSpotNumber",
-    "isNextToBuilding": {
-    "@type": "@id",
-    "@id": "http://example.org/common/isNextToBuilding"
-    },
-    "reliability": "http://example.org/common/reliability", 
-    "providedBy": {
-    "@type": "@id",
-    "@id": "http://example.org/common/providedBy"
-    },
-    "name": "http://example.org/common/name",
-"commercial":
-"http://example.org/vehicle/commercial",
-    "non-commercial": "http://example.org/vehicle/non-commercial",
-"Integer": "http://www.w3.org/2001/XMLSchema#Integer
-}
-{ 
-    "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456",
-    "type": "ContextSourceRegistration",
-    "information": [
-   {
-    "entities": [ 
-    {
-                "id": "urn:ngsi-ld:Vehicle:A456",
-    "type": "Vehicle"
-            }
-    ],
-    "propertyNames": ["brandName","speed"],
-    "relationshipNames": ["isParked"]
-   }, 
-   { 
-    "entities": [
-    {
-                "idPattern": ".*downtown$",
-    "type": "OffStreetParking"
-            },
-    {
-                "idPattern": ".*47$",
-    "type": "OffStreetParking"
-            }
-    ],
-    "propertyNames": ["availableSpotNumber","totalSpotNumber"],
-    "relationshipNames": ["isNextToBuilding"]
-      }
-    ],
-    "endpoint": "http://my.csource.org:1026",
-    "location": {
-    "type": "Polygon",
-    "coordinates": [
-             [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0],
-               [100.0, 1.0], [100.0, 0.0]] ]
-    },
-    "managementInterval": {
-  "startAt": " 2017-11-29T14:53:15Z"
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/commonTerms.jsonld",
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld", 
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Subscription:mySubscription",
-    "type": "Subscription",
-    "entities": [
-    {
-    "type": "Vehicle"
-        }
-    ],
-    "watchedAttributes": ["speed"],
-    "q": "speed>50",
-    "geoQ": {
-    "georel": "near;maxDistance==2000",
-        "geometry": "Point",
-        "coordinates": [-1,100]
-    },
-    "notification": {
-        "attributes": ["speed"],
-        "format": "keyValues",
-        "endpoint": {
-            "uri": "http://my.endpoint.org/notify",
-            "accept": "application/json"
-        }
-    },
-    "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-

The subject of the Context Subscription is Entities of Type Vehicle which speed is greater than 50, and located close to a certain area defined by a reference spatial point. Every time the speed (watched Attribute) of a concerned vehicle, changes, a new notification (including the new speed value) will be received in the specified endpoint.

-

C.5 HTTP REST API Examples

-

C.5.1 Introduction

-

This clause introduces some simple usage examples of the NGSI-LD API (HTTP REST binding). They are not intended to be exhaustive but just a sample for helping readers to understand better the present document. ETSI ISG CIM published a Developer’s Primer with many more examples, see ETSI GR CIM 008 [i.21].

-

C.5.2 Create Entity of Type Vehicle

-

C.5.2.1 HTTP Request

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/ld+json

-
-
-

Content-Length: 556

-
-
-

<Insert Here the JSON-LD representation of a Vehicle as described by [clause C.2.2](15-annex-c-informative-examples-of-using-the-api.html#c.2.2tabvehicle-entity) Vehicle Entity>

-
-

C.5.2.2 HTTP Response

-
-

201 Created

-
-
-

Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567

-
-

C.5.3 Query Entities

-

C.5.3.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” whose brandName attribute is not “Mercedes” . Only give back the brandName attribute and provide the data in the NGSI-LD Simplified Format.

-
-
-

C.5.3.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=Vehicle&q=brandName!=“Mercedes”&format=simplified

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.3.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "brandName": "Volvo",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.4 Query Entities (Pagination)

-

C.5.4.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” . Only give back the brandName attribute and provide the data in the NGSI-LD Simplified Format. Limit the number of entities retrieved to 2.

-
-
-

C.5.4.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type= Vehicle&format=simplified&limit=2

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.4.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
-

Link: </ngsi-ld/v1/entities/?type= Vehicle&format=**simplified**&limit=2&offset=2>; rel=“next”; type=“application/ld+json”

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "brandName": "Volvo",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  },
-  {
-    "id": "urn:ngsi-ld:Vehicle:A456",
-    "type": "Vehicle",
-    "brandName": "Mercedes",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.5 Temporal Query

-

C.5.5.1 Introduction

-
-
-

EXAMPLE 1:

-
-
-

Give back the temporal evolution of the attribute speed of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM.

-
-
-
-
-

EXAMPLE 2:

-
-
-

Give back the temporal evolution of the attribute speed and brandName of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM. As brandName attribute does not have any temporal evolution, brandName attribute is omitted in the response.

-
-
-

C.5.5.2 HTTP Request #1

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ ngsi-ld /latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.5.3 HTTP Response #1

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": [
-      {
-        "type": "Property",
-        "value": 120,
-        "observedAt": "2018-08-01T12:03:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 80,
-        "observedAt": "2018-08-01T12:05:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 100,
-        "observedAt": "2018-08-01T12:07:00Z"
-      }
-    ],
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-] 
-

C.5.5.3 HTTP Request #2

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ ngsi-ld /latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.5.4 HTTP Response #2

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": [
-      {
-        "type": "Property",
-        "value": 120,
-        "observedAt": "2018-08-01T12:03:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 80,
-        "observedAt": "2018-08-01T12:05:00Z"
-      },
-      {
-        "type": "Property",
-        "value": 100,
-        "observedAt": "2018-08-01T12:07:00Z"
-      }
-    ],
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.6 Temporal Query (Simplified Representation)

-

C.5.6.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the temporal evolution of the speed attribute for Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM. Simplified representation is required.

-
-
-

C.5.6.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=temporalValues

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.6.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          120,
-          "2018-08-01T12:03:00Z"
-        ],
-        [
-          80,
-          "2018-08-01T12:05:00Z"
-        ],
-        [
-          100,
-          "2018-08-01T12:07:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.7 Retrieve Available Entity Types

-

C.5.7.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all entity types for which entity instances are currently available in the NGSI-LD system.

-
-
-

C.5.7.2 HTTP Request

-
-

GET /ngsi-ld/v1/types

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.7.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:EntityTypeList:34534657",
-  "type": "EntityTypeList",
-  "typeList": [
-    "Vehicle",
-    "OffStreetParking",
-    "http://example.org/parking/ParkingSpot"
-  ]
-}
-
-
-

NOTE:

-
-
-

All entity types that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs).

-
-
-

C.5.8 Retrieve Details of Available Entity Types

-

C.5.8.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of all entity types for which entity instances are currently available in the NGSI-LD system.

-
-
-

C.5.8.2 HTTP Request

-
-

GET /ngsi-ld/v1/types?details=true

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.8.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
[
-  {
-    "id": "http://example.org/vehicle/Vehicle",
-    "type": "EntityType",
-    "typeName": "Vehicle",
-    "attributeNames": [
-      "brandName",
-      "isParked",
-      "location",
-      "speed"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/OffStreetParking",
-    "type": "EntityType",
-    "typeName": "OffStreetParking",
-    "attributeNames": [
-      "availableSpotNumber",
-      "isNextToBuilding",
-      "location",
-      "totalSpotNumber"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/ParkingSpot",
-    "type": "EntityType",
-    "typeName": "http://example.org/parking/ParkingSpot",
-    "attributeNames":[
-      "location",
-      "http://example.org/parking/status"
-    ]
-  }
-] 
-
-
-

NOTE:

-
-
-

The type name of all entity types and all attribute names that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs). The id is always an FQN.

-
-
-

C.5.9 Retrieve Available Entity Type Information

-

C.5.9.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of entity type “Vehicle” (for which entity instances are currently available in the NGSI-LD system).

-
-
-

C.5.9.2 HTTP Request

-
-

GET /ngsi-ld/v1/types/Vehicle

-
-
-

[Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.9.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "http://example.org/vehicle/Vehicle",
-  "type": "EntityTypeInfo",
-  "typeName": "Vehicle",
-  "entityCount": 2,
-  "attributeDetails": [
-    {
-      "id": "http://example.org/vehicle/brandName",
-      "type": "Attribute",
-      "attributeName": "brandName",
-      "attributeTypes": [
-        "Property"
-      ]
-    },
-    {
-      "id": "http://example.org/vehicle/isParked",
-      "type": "Attribute",
-      "attributeName": "isParked",
-      "attributeTypes": [
-        "Relationship"
-      ]
-    },
-    {
-      "id": "https://uri.etsi.org/ngsi-ld/location",
-      "type": "Attribute",
-      "attributeName": "location",
-      "attributeTypes": [
-        "GeoProperty"
-      ]
-    },
-    {
-      "id": "http://example.org/vehicle/speed",
-      "type": "Attribute",
-      "attributeName": "speed",
-      "attributeTypes": [
-        "Property"
-      ]
-    }
-  ]
-}
-

C.5.10 Retrieve Available Attributes

-

C.5.10.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all attribute names for which entity instances are currently available in the NGSI-LD system that have an attribute with the respective name.

-
-
-

C.5.10.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.10.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:AttributeList:56534657",
-  "type": "AttributeList",
-  "attributeList": [
-    "brandName",
-    "isParked",
-    "location",
-    "speed",
-    "http://example.org/parking/status"
-  ]
-}
-
-
-

NOTE:

-
-
-

The attribute names that can be found in the provided @context are given as short names, the others as fully qualified names (FQNs).

-
-
-

C.5.11 Retrieve Details of Available Attributes

-

C.5.11.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of all attributes for which entity instances are currently available in the NGSI-LD system to which an attribute with the respective attribute name belongs.

-
-
-

C.5.11.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes?details=true

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.11.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
[
-  {
-    "id": "http://example.org/vehicle/brandName",
-    "type": "Attribute",
-    "attributeName": "brandName",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "http://example.org/vehicle/isParked",
-    "type": "Attribute",
-    "attributeName": "isParked",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "https://uri.etsi.org/ngsi-ld/location",
-    "type": "Attribute",
-    "attributeName": "location",
-    "typeNames": [
-      "Vehicle",
-      "OffStreetParking",
-      "http://example.org/parking/ParkingSpot"
-    ]
-  },
-  {
-    "id": "http://example.org/vehicle/speed",
-    "type": "Attribute",
-    "attributeName": "speed",
-    "typeNames": [
-      "Vehicle"
-    ]
-  },
-  {
-    "id": "http://example.org/parking/status",
-    "type": "Attribute",
-    "attributeName": "http://example.org/parking/status",
-    "typeNames": [
-      "http://example.org/parking/ParkingSpot"
-    ]
-  }
-] 
-
-
-

NOTE:

-
-
-

The attribute name and all type names that can be found in the provided @context are given as short names, the others as Fully Qualified Names (FQNs). The id is always an FQN.

-
-
-

C.5.12 Retrieve Available Attribute Information

-

C.5.12.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the details of the attribute named brandName (for which entity instances with an attribute of this name are currently available in the NGSI-LD system).

-
-
-

C.5.12.2 HTTP Request

-
-

GET /ngsi-ld/v1/attributes/brandName

-
-
-

[Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]

-
-
-

Accept: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.12.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "http://example.org/vehicle/brandName",
-  "type": "Attribute",
-  "attributeName": "brandName",
-  "attributeTypes": ["Property"],
-  "typeNames": ["Vehicle"],
-  "attributeCount": 2
-}
-

C.5.13 Query Entities (Natural Language Filtering)

-

C.5.13.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type “Vehicle” where the marque attribute in British English is “Vauxhall Viva” . Only give back the marque attribute and provide the data in the NGSI-LD Simplified Format and only return language strings in German.

-
-
-

C.5.13.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]== “Vauxhall Viva”&format =simplified&lang=de

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.13.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:A4567",
-    "type": "Vehicle",
-    "marque": "Opel Karl",
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.14 Temporal Query (Aggregated Representation)

-

C.5.14.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the maximum and average speed of Entities of type “Vehicle” whose brandName attribute is not “Mercedes” between the 1 st of August at noon and the 1 st of August at 01 PM, aggregated by periods of 4 minutes.

-
-
-

C.5.14.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=aggregatedValues

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.14.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "speed": {
-      "type": "Property",
-      "max": [
-        [
-          120,
-          "2018-08-01T12:00:00Z",
-          "2018-08-01T12:04:00Z"
-        ],
-        [
-          100,
-          "2018-08-01T12:04:00Z",
-          "2018-08-01T12:08:00Z"
-        ]
-      ],
-      "avg": [
-        [
-          120,
-          "2018-08-01T12:00:00Z",
-          "2018-08-01T12:04:00Z"
-        ],
-        [
-          90,
-          "2018-08-01T12:04:00Z",
-          "2018-08-01T12:08:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-

C.5.15 Scope Queries

-

C.5.15.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back all the Entities of type ” OffStreetParking” that are within the Scope /Madrid/Centro or /Madrid/Cortes .

-
-
-

C.5.15.2 HTTP Request

-
-

GET /ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ=“/Madrid/Centro,/Madrid/Cortes”

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.15.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-
[
-   {
-      "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-      "type": "OffStreetParking",
-      "scope": "/Madrid/Centro",
-      "name": {
-         "type": "Property",
-         "value": "Downtown One"
-      },
-      "availableSpotNumber": {
-         "type": "Property",
-         "value": 121,
-         "observedAt": "2017-07-29T12:05:02Z",
-         "reliability": {
-            "type": "Property",
-            "value": 0.7
-         },
-         "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-         }
-      },
-      "totalSpotNumber": {
-         "type": "Property",
-         "value": 200
-      },
-      "location": {
-         "type": "GeoProperty",
-         "value": {
-            "type": "Point",
-            "coordinates": [
-               -8.5,
-               41.2
-            ]
-         }
-      },
-      "@context": [
-         "http://example.org/ngsi-ld/latest/parking.jsonld",
-         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-      ]
-   },
-   {
-      "id": "urn:ngsi-ld:OffStreetParking:Corte4",
-      "type": "OffStreetParking",
-      "scope": [
-            "/Madrid/Cortes",
-            "/Company894/UnitC"
-      ],
-      "name": {
-         "type": "Property",
-         "value": "Corte4"
-      },
-      "availableSpotNumber": {
-         "type": "Property",
-         "value": 121,
-         "observedAt": "2017-07-29T12:05:02Z",
-         "reliability": {
-            "type": "Property",
-            "value": 0.7
-         },
-         "providedBy": {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Camera:C1"
-         }
-      },
-      "totalSpotNumber": {
-         "type": "Property",
-         "value": 100
-      },
-      "location": {
-         "type": "GeoProperty",
-         "value": {
-            "type": "Point",
-            "coordinates": [
-               -8.6,
-               41.3
-            ]
-         }
-      },
-      "@context": [
-         "http://example.org/ngsi-ld/latest/parking.jsonld",
-         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-      ]
-   }
-]
-

C.5.16 Temporal Scope Queries

-

C.5.16.1 Introduction

-
-
-

EXAMPLE:

-
-
-

Give back the speed of all the Entities of type “Vehicle” that have been within the Scope /Madrid/Centro between the 1 st of August 2018 at noon and the 1 st of August 2018 at 01 PM. Note that the value of the Scope has to match for the given timeframe, which means it is possible that it has been set before, e.g. on 1 st of August 2018 at 11 AM.

-
-
-

C.5.16.2 HTTP Request

-
-

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ=“/Madrid/Centro”

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-

C.5.16.3 HTTP Response

-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-

Vehicle B9211 has already been within the Scope /Madrid/Centrobefore the beginning of the request interval, whereas Vehicle A8311 only entered the Scope within the request interval. Thus in the latter case only Property values are included that have been observed after the Scope has become valid.

-

C.6 Date Representation

-

In NGSI-LD, a TemporalProperty is represented only by its value, i.e. no sub-Properties of TemporalProperty nor sub-Relationships of TemporalProperty can be conveyed. In more formal language, a TemporalProperty does not allow reification. The term TemporalProperty has been reserved for non-reified structural timestamps (observedAt, createdAt, modifiedAt, deletedAt), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as timeproperty in Temporal Queries as mandated by clause 4.11.

-

The following examples show how time values (Date, Time, or DateTime) can be represented in NGSI-LD as reified Properties. For a reified Property whose value is assigned the JSON type Date, DateTime or Time, one mechanism is to use the Property’s valueType to hold the datatype (“Date”, “Datetime” or “Time”), as shown below:

-

Alternatively the data can be a structured to use the JSON-LD @value syntax structure, as shown below:

-

A third alternative to achieve the same result would be to use JSON-LD “type coercion”. With type coercion, values with a special data type are defined with @type in the @context. This enforces the correct type for any occurrence. Such an @context fragment is shown below:

-

The above does not work, when using the @context to perform compaction, in the normalized and compact representation of NGSI-LD, due to reification of the Property, because in this case testedAt is a complex JSON object, which cannot be compacted to a DateTime type as the @context specifies. Thus, the full URI http://example.org/test/testedAt is kept, instead of the short name testedAt. In summary, user @contexts used for the normalized and compact NGSI-LD representation cannot use the JSON-LD type coercion feature.

-

However, in the simplified (keyValue) representation case, such an @context with the specification of testedAt could be used, as there is no reification.

-

As a side note, when using the above @value + @type approach, since type is mapped to @type in the NGSI-LD core @context, JSON-LD compaction will result in the following compacted value, instead of the one shown above, because @type is compacted to type:

-
[
-  {
-    "id": "urn:ngsi-ld:Vehicle:B9211",
-    "type": "Vehicle",
-    "scope": {
-     "type": "Property",
-      "values": [
-        [
-          "/Madrid/Centro",
-          "2018-08-01T11:00:00Z"
-        ]
-     ]
-       },  
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          30,
-          "2018-08-01T12:03:00Z"
-        ],
-        [
-          60,
-          "2018-08-01T12:05:00Z"
-        ],
-        [
-          50,
-          "2018-08-01T12:07:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  },
-  {
-    "id": "urn:ngsi-ld:Vehicle:A8311",
-    "type": "Vehicle",
-    "scope": {
-     "type": "Property",
-      "values": [
-        [
-          [
-             "/Madrid/Centro",
-             "/Company123/UnitA"
-          ],
-          "2018-08-01T12:10:00Z"
-        ]
-     ]
-       },  
-    "speed": {
-      "type": "Property",
-      "values": [
-        [
-          40,
-          "2018-08-01T12:12:00Z"
-        ],
-        [
-          60,
-          "2018-08-01T12:14:00Z"
-        ],
-        [
-          50,
-          "2018-08-01T12:16:00Z"
-        ]
-      ]
-    },
-    "@context": [
-      "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-  }
-]
-{
-  "id": "urn:ngsi-ld:Vehicle:B9211",
-  "type": "Vehicle",
-  "testedAt": {
-    "type": "Property",
-    "value":"2018-12-04T12:00:00Z"
-    "valueType": "DateTime"
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-  "id": "urn:ngsi-ld:Vehicle:B9211",
-  "type": "Vehicle",
-  "testedAt": {
-    "type": "Property",
-    "value": {
-      "@type": "DateTime",
-      "@value": "2018-12-04T12:00:00Z"
-    }
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/vehicle.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-"testedAt": {
-  "@type": "https://uri.etsi.org/ngsi-ld/DateTime",
-  "@id": "http://example.org/test/testedAt"
-}
-"value": {
-  "type": "DateTime",
-  "@value": "2018-12-04T12:00:00Z"
-}
-

C.7 @context utilization clarifications

-

When expanding or compacting JSON-LD terms, the JSON-LD @context to be used is always the one provided in the current API request. For the benefit of users and implementers the following examples illustrate this concept.

-

The scenario starts with the creation of an Entity using a JSON-LD @context as follows:

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/ld+json

-
-
-

Content-Length: 200

-
-

The content of the @context utilized for the referred Entity creation (at http://example.org/ngsi-ld/latest/parking.jsonld) is as follows:

-

At Entity creation time the implementation will perform the expansion of terms using the JSON-LD @context depicted above.

-

Now it is needed to retrieve our initial Entity. For retrieving such Entity, this time, a different JSON-LD @context is going to be utilized, as follows:

-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffStreetParking",
-  "name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "availableSpotNumber": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-     },
-  "totalSpotNumber": {
-    "type": "Property",
-    "value": 200
-  },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-{
-"OffStreetParking": "http://example.org/parking/OffStreetParking",
-"availableSpotNumber": "http://example.org/parking/availableSpotNumber",
-"totalSpotNumber": "http://example.org/parking/totalSpotNumber",
-"name": "http://example.org/parking/name"
-}
-{
-"OffP": "http://example.org/parking/OffStreetParking",
-"ava": "http://example.org/parking/availableSpotNumber",
-"total": "http://example.org/parking/totalSpotNumber"
-}
-

This new @context, even though it makes use of the same set of Fully Qualified Names, is defining new short strings as terms. The reasons for that could be multiple: to facilitate data consumption by clients, to save some bandwidth, to enable a more (or less) human-readable response payload body in a language different than English, etc.

-

In this particular case, the result of the Entity retrieval will be as depicted below. It can be observed that the terms defined by the JSON-LD @context provided at retrieval time are used to render the Entity content (compaction), and not the terms that were provided at creation time (which may be no longer known by the broker).

-

It is also interesting to note that the @context array of the response payload body contains, indeed, our header-supplied @context:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1

-
-
-

Accept: application/ld+json

-
-
-

Link: <http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "OffP",
-  "name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "ava": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-  },
-  "total": {
-  "type": "Property",
-    "value": 200
-    },
-  "@context": [
-    "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld",
-    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-  ]
-}
-

Another interesting case to note is the one when an @context with no matching terms or no @context at all is supplied. See the following example:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1

-
-
-

Accept: application/ld+json

-
-
{
-  "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
-  "type": "http://example.org/parking/OffStreetParking",
-  "http://example.org/parking/name": {
-    "type": "Property",
-    "value": "Downtown One"
-  },
-  "http://example.org/parking/availableSpotNumber": {
-    "type": "Property",
-    "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-  },
-  "http://example.org/parking/totalSpotNumber": {
-    "type": "Property",
-    "value": 200
-  },
-  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-}
-

In this particular case it can be observed that the user names (Entity Type, Attributes) in the response payload body have not been compacted, and as a result the Fully Qualified Names are included. However, the core API terms have been compacted, as the Core @context is always considered to be implicitly present if not specified explicitly (and that is why it is included in the JSON-LD response, as mandated by the specification).

- -

The JSON-LD Specification [2] states clearly that only one HTTP Link header with the link relationship <http://www.w3.org/ns/json-ld#context> is required to appear. Such statement has implications in terms of providing the JSON-LD @context when using the NGSI-LD API. The main implication is that if the @context is a compound one, i.e. an @context which references multiple individual @context, served by resources behind different URIs, then a wrapper @context has to be created and hosted. The final aim is that only one @context is referenced from the JSON-LD Link header. This can be illustrated with an example:

-

Imagine that it is desired to create an Entity providing @context terms which are defined in two different JSON-LD @context resources:

-
-
    -
  • http://example.org/vehicle/v1/vehicle-context.jsonld
    • -
  • https://schema.org
    • -
-
-

If a developer wants to reference these two @context resources from a Link header, a wrapper @context can be easily created as follows:

-
{
-   "@context": [
-       "http://example.org/vehicle/v1/vehicle-context.jsonld",
-       "https://schema.org",
-       "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-   ]
-}
-

As such wrapper @context needs to be referenced from a Link header by using a URI, then it will have to be hosted at some place on the Web. Usually, developers will host @context using popular and simple solutions such as GitHub or GitLab pages. As a result, developers will be able to use @context in queries or when using “application/json” as main content type managed by their applications.

-

It is a good practice to include the Core @context in the wrapper @context so it can be used, off-the-shelf, by external JSON-LD processing tools. However, it should be noted this is not necessary for NGSI-LD, as the Core @context is always implicitly included.

-

Then, using such wrapper @context, (in our example hosted at https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), the developer will be able to issue requests like:

-
-

POST /ngsi-ld/v1/entities/

-
-
-

Content-Type: application/json

-
-
-

Content-Length: 200

-
-
-

Link: <https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
{
-    "id": "urn:ngsi-ld:Vehicle:V1",
-    "type": "Vehicle",
-    "builtYear": {
-    "type": "Property",
-        "value": "2014"
-    },
-    "speed": {
-        "type": "Property",
-        "value": 121,
-    "observedAt": "2017-07-29T12:05:02Z"
-    }
-}
-
-

201 Created

-
-
-

Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1

-
-
-

Link: < https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld >; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1

-
-
-

Accept: application/ld+json

-
-
-

Link: <https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; rel=“http://www.w3.org/ns/json-ld#context”; type=“application/ld+json”

-
-
-

200 OK

-
-
-

Content-Type: application/ld+json

-
-

Observe that in this case the broker is responding with the same wrapper @context in the Link header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is “application/ld+json”). However, that could not be always the case, as there could be situations where the broker could need to provide a wrapper @context hosted by itself, for instance, when there are inline @context terms or when the Core @context has not been previously included by the wrapper @context (not recommended) provided within developer’s requests.

-

C.9 @context processing clarifications

-

JSON-LD Specification [2] says that “If a term is redefined within a context, all previous rules associated with the previous definition are removed”. In addition, it is stated that “Multiple contexts may be combined using an array, which is processed in order”.

-

In contrast to the JSON-LD Specification, the NGSI-LD specification states that the Core @context is protected and has to remain immutable. This essentially means that the Core @context has final precedence and, therefore, is always to be processed as the last one in the @context array. For clarity, data providers should place the Core @context in the final position. From the point of view of Data providers, care has to be taken so that there are no unexpected or undesired term expansions. See the following example:

-

The problem of the example above is that the term “location” is defined in both the Core @context and the schema.org user @context and the Core @context takes precedence for the expansion. In these situations, if one wanted to refer to the schema.org “location”, the solution is to prefix the conflicting terms, so that there cannot be any clashing. Therefore, if the intent is to refer to <https://schema.org/location> throughout, the example above can be modified as shown below:

-

Note that the Core @context should be placed in the last position of the @context array. NGSI-LD implementations are required to render content following this approach, which has been undertaken in order to maximize compatibility with JSON-LD processing tools. This example works because the “schema:” prefix has already been defined by the schema.org @context.

-

C.10 ValueType datatype utilization clarifications

-

Using JSON-LD [2] syntax, typed values can be expressed using the JSON-LD @type keyword when defining a term, where @type value holds a URI which indicates the value’s datatype. However, it can be desirable for a Context Broker to be able to hold simpler untyped values within a Property’s value attribute and separately use a Property’s valueType to hold the value’s datatype. This format can be used to accommodate multiple acceptable datatype formats for the data to be held within a single Property and still hold sufficient meta data to be able to distinguish between them.

-

For example, consider an ontology for an Entity of type “Place” which has an address Property, where the address Property can either be an unstructured address in the form of a “String”or a structured “PostalAddress” JSON Object with street, city and country attributes – the following JSON-LD schema can be defined:

-

Example JSON-LD schema

-

Then the following two Entities of type ”Place”can be created using the address.valueType Property to distinguish between the two formats:

-
{
-    "id": "urn:ngsi-ld:Vehicle:V1",
-    "type": "Vehicle",
-    "builtYear": {
-    "type": "Property",
-        "value": "2014"
-    },
-    "speed": {
-        "type": "Property",
-        "value": 121,
-  "observedAt": "2017-07-29T12:05:02Z"
-    },
-    "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld"
-}
-{
-    "id": "urn:ngsi-ld:Building:B1",
-    "type": "Building",
-    "name": {
-    "type": "Property",
-        "value": "Empire State"
-    },
-    "location": {
-        "type": "Property",
-        "value": "20 West 34th Street, New York City, NY 10001"
-    },
-    "@context": [
-        "https://schema.org/version/latest/schemaorg-current-https.jsonld",
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "id": "urn:ngsi-ld:Building:B1",
-    "type": "Building",
-    "name": {
-        "type": "Property",
-        "value": "Empire State"
-    },
-    "schema:location": {
-        "type": "Property",
-        "value": "20 West 34th Street, New York City, NY 10001"
-    },
-    "@context": [
-        "https://schema.org/version/latest/schemaorg-current-https.jsonld",
-        "http://example.org/ngsi-ld/latest/parking.jsonld",
-        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
-    ]
-}
-{
-    "example": "http://example.org/",
-    "xsd": "http://www.w3.org/2001/XMLSchema#",
-    "address": "example:address",
-    "city": "example:city",
-    "country": "example:country",
-    "street": "example:street",
-    "Place": "example:Place"
-    "PostalAddress": "example:PostalAddress",
-    "String": "xsd:String"
-}
-[
-    {
-        "id": "urn:ngsi-ld:Place:27182",
-        "type": "Place",
-        "address": {
-            "type": "Property",
-            "value": "Pariser Platz, Berlin, Germany",
-            "valueType": "String"
-        }
-    },
-    {
-        "id": "urn:ngsi-ld:Place:31415",
-        "type": "Place",
-        "address": {
-            "type": "Property",
-            "value": {
-                "street": "Straße des 17. Juni",
-                "city": "Berlin",
-                "country": "Germany"
-            },            "valueType": "PostalAddress"
-        }
-    }
-]
-

C.11 Entity with digital signature for a Property

-

As specified in [], the atomic piece of information that creators can digitally sign in an NGSI-LD ecosystem is each single Attribute of an Entity. In the following example, an Entity of type “Store” with two Properties, “address” and “location” is presented. The “address” Property is digitally signed. The signature is created using one Ed25519 instantiation of the Edwards-Curve Digital Signature Algorithm (EdDSA).The used crypto suite is “eddsa-rdfc-2022”.

-
-
-

EXAMPLE:

-
-
-

Entity of type “Store” with two Properties. The “address” Property is digitally signed.

-
-
-

{

-

“id”: “urn:ngsi-ld:Store:002”,

-

“type”: “Store”,

-

“address”: {

-

“type”: “Property”,

-

“value”: {

-

“streetAddress”: [“Tiger Street 4”, “al”],

-

“addressRegion”: “Metropolis”,

-

“addressLocality”: “Cat City”,

-

“postalCode”: “42420”

-

}

-

“ngsildproof”: {

-

“type”: “Property”,

-

“entityIdSealed”: “urn:ngsi-ld:Store:002”,

-

“entityTypeSealed”: “Store”,

-

“proof”: {

-

“type”: “DataIntegrityProof”,

-

“created”: “2025-01-27T21:02:24Z”,

-

“verificationMethod”: “https://example.edu/issuers/565049#z6MkwXG2WjeQnN.…Hc6SaVWoT”,

-

“cryptosuite”: “eddsa-rdfc-2022”,

-

“proofPurpose”: “assertionMethod”,

-

“proofValue”: “z3XrH3diVCqpVHXkE7WbnictqyQCkJBGTx.…NRTzmuoWU1Y2FyqGfSV9eS”

-

}

-

}

-

},

-

“location”: {

-

“type”: “GeoProperty”,

-

“value”: {

-

“type”: “Point”,

-

“coordinates”: [57.5522, -20.3484]

-

}

-

},

-

“@context”: “https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld”

-

}

-
- - - - - diff --git a/API/16-annex-d-informative-transformation-algorithms.html b/API/16-annex-d-informative-transformation-algorithms.html deleted file mode 100644 index ea12b3cab9760f8ee3e974c5c3d1eced842fc10d..0000000000000000000000000000000000000000 --- a/API/16-annex-d-informative-transformation-algorithms.html +++ /dev/null @@ -1,1750 +0,0 @@ - - - - - - - -Annex D (informative): Transformation Algorithms - - - - - - - - - - - - -
-

Annex D (informative): Transformation Algorithms

-

D.1 Introduction

-

These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification [2]).

-

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

-

This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated @context) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model.

-
-
-

NOTE:

-
-
-

An early implementation of this algorithm can be found at [i.5].

-
-
-

Let:

-
-
    -
  • G be a graph defined as follows:
    • -
-
-
-
    -
  • Let N be G’s top level node.
    • -
  • N is an Entity instance of type T or types Ts. Type name is “AliasT” or there is an Array of Type names [“AliasT1”, …,“AliasTn”], N’s identifier is I.
    • -
  • N has 0 or more associated Property. Each Property (Psi) is defined as follows:
    • -
-
-
-
    -
  • Property type identifier is Pi.
    • -
  • Property name is “AliasPi”.
    • -
  • Property Value is Vi.
    • -
  • Property Value’s associated data type is Di.
    • -
-
-
-
    -
  • N is the subject of 0 or more Relationship. Each Relationship is defined as follows:
    • -
-
-
-
    -
  • Relationship type identifier is Ri.
    • -
  • Relationship name is “AliasRi”.
    • -
  • Relationship target object identifier is Robji.
    • -
-
-
-
    -
  • O be a JSON object initialized to the empty object ({}).
    • -
  • C be a JSON-LD @context initialized as described by annex B.
    • -
-
-

The algorithm should run as follows, provided all the preconditions defined above are satisfied:

-
-
    -
  1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> … <"AliasTn", Tn>.
    2. -
  2. Add to O two new members:
    3. -
-
-
-
    -
  1. <"id", I>.
    2. -
-
-
-
    -
  1. <"type", "AliasT"> or <"type", ["AliasT1", ...,"AliasTn"]> .”>.
    2. -
-
-
-
    -
  1. For each Property Psi (Pi, “AliasP”, Vi, Di) associated to N:
    2. -
-
-
-
    -
  1. Run Algorithm ALG1.1 taking the following inputs:
    2. -
-
-
-
    -
  • Ps → Psi.
    • -
  • O → O.
    • -
  • C → C.
    • -
-
-
-
    -
  1. For each Relationship Rs (Ri, AliasRi, Robji) associated to N:
    2. -
-
-
-
    -
  1. Run Algorithm ALG1.2 taking the following inputs:
    2. -
-
-
-
    -
  • Rs → Rsi.
    • -
  • O → O.
    • -
  • C → C.
    • -
-
-
-
    -
  1. Return (O, C) and end of the algorithm.
    2. -
-
-

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

-

Let Ps be the Property that has to be transformed. It is defined by (P, “AliasP”, V, D), where P denotes a Property Type Id, “AliasP” is the Property name, V is the Property Value and D is the Property Value’s data type.

-

Ps might be associated to extra Properties or Relationships.

-

Let O be the output JSON-LD object and C the associated JSON-LD context:

-
-
    -
  1. Execute the following steps:
    2. -
-
-
-
    -
  1. If no member with “AliasP” is present in O, add a new member to O with key “AliasP” and value an object structure, let it be named Op as defined in the following. Otherwise, add all existing members with “AliasP” to a JSON-LD array and in addition put the object structure Op as defined in the following:
    2. -
-
-
-
    -
  • <"type", "Property">.
    • -
  • If D is not a native JSON data type add a new member to Op with name “value” and which value has to be an object structure as follows:
    • -
-
-
-
    -
  1. <"@type", D>.
    2. -
-
-
-
    -
  1. <"@value", V>.
    2. -
-
-
-
    -
  • Else If D is a native JSON data type add a new member to Op as follows:
    • -
-
-
-
    -
  1. <"value", V>.
    2. -
-
-
-
    -
  1. Add a new member to C as follows:
    2. -
-
-
-
    -
  • <"AliasP", P>.
    • -
-
-
-
    -
  1. For each Property associated to Ps (Pss) recursively run the present algorithm (ALG1.1) taking the following inputs:
    2. -
-
-
-
    -
  • Ps → Pss.
    • -
  • O → Op.
    • -
  • C → C.
    • -
-
-
-
    -
  1. For each Relationship associated to Ps (Rss) run algorithm ALG1.2 taking the following inputs:
    2. -
-
-
-
    -
  • Rs → Rss.
    • -
  • O → Op.
    • -
  • C → C.
    • -
-
-
-
    -
  1. Return (O,C) and end of the algorithm.
    2. -
-
-

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

-

Let Rs be the Relationship that has to be transformed. It is defined by (R, “AliasR”, Robj), where R denotes a Relationship Type Id, “AliasR” is the Relationship’s name and Robj is the identifier of the target object of the Relationship.

-

Rs might be associated to extra Properties or Relationships.

-

Let O be the output JSON-LD object and C the current JSON-LD context:

-
-
    -
  1. Execute the following statements:
    2. -
-
-
-
    -
  1. If no member with “AliasR” is present in O, add a new member to O with key “AliasR” and value an object structure, let it be named Or, and defined as in the following. Otherwise, add all existing members with “AliasR” to a JSON-LD array and in addition put the object structure Or as defined in the following:
    2. -
-
-
-
    -
  • <"object", Robj>.
    • -
  • <"type", "Relationship">.
    • -
-
-
-
    -
  1. For each Property associated to Rs (Pss) run the algorithm ALG1.1 taking the following inputs:
    2. -
-
-
-
    -
  • Ps → Pss.
    • -
  • O → Or.
    • -
  • C → C.
    • -
-
-
-
    -
  1. For each Relationship associated to Rs (Rss) recursively run the present algorithm ALG1.2 taking the following inputs:
    2. -
-
-
-
    -
  • Rs → Rss.
    • -
  • O → Or.
    • -
  • C → C.
    • -
-
-
-
    -
  1. Return (O,C) and end of the algorithm.
    2. -
-
-
- - - - - diff --git a/API/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html b/API/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html deleted file mode 100644 index cd8251032ea9e90ed3e695b4c068ae539d82b842..0000000000000000000000000000000000000000 --- a/API/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html +++ /dev/null @@ -1,1516 +0,0 @@ - - - - - - - -Annex E (informative): RDF-compatible specification of NGSI-LD meta-model - - - - - - - - - - - - -
-

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

-

The content of this annex is now in ETSI GS CIM 006 [i.8].

-
- - - - - diff --git a/API/18-annex-f-informative-conventions-and-syntax-guidelines.html b/API/18-annex-f-informative-conventions-and-syntax-guidelines.html deleted file mode 100644 index f43138953a5786708da172e656682632ad62907b..0000000000000000000000000000000000000000 --- a/API/18-annex-f-informative-conventions-and-syntax-guidelines.html +++ /dev/null @@ -1,1589 +0,0 @@ - - - - - - - -Annex F (informative): Conventions and syntax guidelines - - - - - - - - - - - - -
-

Annex F (informative): Conventions and syntax guidelines

-

When new terms are defined, they are marked in bold, and terms are capitalized thereafter.

-
-
-

EXAMPLE 1:

-
-
-

NGSI-LD Linked Entity , Linked Entity .

-
-
-

API Parameter names are always in lowercase.

-
-
-

EXAMPLE 2:

-
-
-

options .

-
-
-

Entity Types are defined using lowercase but with a starting capital letter.

-
-
-

EXAMPLE 3:

-
-
-

Vehicle, Building, ParkingSpace.

-
-
-

JSON-LD nodes and terms are always defined using camel case notation starting with lower case.

-
-
-

EXAMPLE 4:

-
-
-

createdAt , value , unitCode .

-
-
-

When referring to special terms, data types or words defined previously in the present document or by other referenced specifications, italics format is used.

-
-
-

EXAMPLE 5:

-
-
-

ListRelationship, GeoProperty, Geometry, Second, Number .

-
-
-

When referring to literal strings double quotes are used.

-
-
-

EXAMPLE 6:

-
-
-

“application/json” , “Subscription” .

-
-
-

When referring to the JSON-LD Context the mnemonic text string @context is used as a placeholder.

-

All the dates and times are given in UTC format.

-
-
-

EXAMPLE 7:

-
-
-

2018-02-09T11:00:00Z .

-
-
-

The measurement units used in the API are those defined by the International System of Units.

-
-
-

EXAMPLE 8:

-
-
-

The distance in geo-queries is provided in meters.

-
-
-

When defining application-specific elements or API extensions the same conventions and syntax guidelines should be followed.

-
- - - - - diff --git a/API/19-annex-g-informative-localization-and-internationalization-support.html b/API/19-annex-g-informative-localization-and-internationalization-support.html deleted file mode 100644 index 6e8e50807ac7199f97e5052e9add4e10788ddbda..0000000000000000000000000000000000000000 --- a/API/19-annex-g-informative-localization-and-internationalization-support.html +++ /dev/null @@ -1,1709 +0,0 @@ - - - - - - - -Annex G (informative): Localization and Internationalization Support - - - - - - - - - - - - -
-

Annex G (informative): Localization and Internationalization Support

-

G.0 Foreword

-

These algorithms described below are informative, but NGSI-LD implementations should aim at either implementing them as they are described here or providing equivalent @context elements for their payloads to provide interoperability with their internationalized context entities.

-

G.1 Introduction

-

G.1.0 Foreword

-

Since Internationalization is not core to context information management, any direct support within NGSI-LD systems is limited. Annex G proposes a series of best practices for maintaining, querying and displaying interoperable internationalized data.

-

The content of the @context utilized for the referred Entities within these examples uses pre-existing URNs used for internationalization and is as follows:

-

G.1.1 Associating an Entity with a Natural Language

-

Where a context Entity is associated with a single natural language, include a well-defined Property indicating the natural language of the content. For example an Event taking place in French may be defined as follows:

-

G.1.2 Associating a Property with a Natural Language

-

Where a Property of a context entity can be associated to one more natural language, include additional metadata as a sub-Property of that Property. For example, a Hotel with booking forms available in English, French and German may be defined as follows:

-

G.1.3 Associating as equivalent entity

-

Where equivalent context entities in multiple natural languages exist, they may be associated with each other through the use of a one-to-many relationship, where each relationship holds an additional sub-Property indicating the natural language of the equivalent entities.

-

For example, three Events (such as a walking tour which is available in English, French and German) may be associated to each other as follows:

-
{
-"inLanguage": "http://schema.org/inLanguage",
-"sameAs": "http://schema.org/sameAs"
-}
-{
-    "type": "Event",
-    "id": "urn:ngsi-ld:Event:bonjourLeMonde",
-    "name": {
-        "type": "Property",
-        "value": "Bonjour le Monde" 
-    },
-    "description": {
-         "type": "Property",
-         "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple" 
-    },
-    "inLanguage": {
-        "type": "Property",
-        "value": "fr"   
-    }
-}
-{
-    "type": "Hotel,
-    "id": "urn:ngsi-ld:Hotel:XXXXX",
-    "name": {
-        "type": "Property",
-        "value": "Grand Hotel" 
-    },
-    "bookingUrl": {
-        "type": "Property",
-        "value": [
-            "http://example.com/booking-in-french/", 
-            "http://example.com/booking-in-english/", 
-            "http://example.com/booking-in-german/"
-        ],
-        "inLanguage": { 
-            "type": "Property", 
-            "value": ["fr", "en", "de" ]
-        }
-    }
-}
-{
-    "type": "Event",
-    "id": "urn:ngsi-ld:Event:bonjourLeMonde",
-    "name": {
-        "type": "Property",
-        "value": "Bonjour le Monde" 
-    },
-    "sameAs": [
-        {
-            "type": "Relationship",
-            "datasetId" : "urn:ngsi-ld:Relationship:1",
-            "object": "urn:ngsi-ld:Event:helloWorld",
-            "inLanguage": {
-                    "type": "Property",
-                    "value": "en"   
-            }
-        },
-        {
-            "type": "Relationship",
-            "object": "urn:ngsi-ld:Event:halloWelt",
-            "inLanguage": {
-                    "type": "Property",
-                    "value": "de"   
-            }
-        }
-    ]
- }
-

G.2 Natural Language Collation Support

-

G.2.0 Foreword

-

All strings within an NGSI-LD system are defined and sorted as a sequence of Unicode characters. As such there is no simple collation mechanism to query entities ignoring case, diacritic marks or matching diphthong single letters such as the German “ö” to also match with “oe”.

-

Many databases support a degree of natural language support, in general collation support will always depend upon the underlying database and as such will vary from implementation to implementation. This therefore and cannot be standardized and exposed as part of the context information management API. Furthermore, collation is slow and processor intensive, and for massive systems is better achieved using a separate index.

-

For systems that require it, this clause proposes a mechanism as an extension to a NGSI-LD Context Broker which can be modified and used to offer collation support to the natural language attributes found within context entities where necessary through creating, querying and maintaining an additional property of a property for collated attributes.

-

G.2.1 Maintain collations as metadata

-
-
    -
  • Create a subscription on the attribute (e.g. name)
    • -
  • Create a simple microservice to add/upsert a name.collate property-of-a-property using a simple function to strip all diacritic marks - for example:
    • -
-
-
-

str.normalize(“NFD”).replace(/[\u0300-\u036f]/g, ““).toLower()

-
-

Other substitutions could be made where local spelling rules vary (for example different for German ö = oe).

-

G.2.2 Route language sensitive queries via a proxy

-

Create a simple forwarding proxy around the NGSI-LD system. For any urls with a q param (and a collate flag) run a clean-up of the q param and amend the query string:

-

The following request on the proxy:

-
-

GET /ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name

-
-

is altered on the fly and is sent to the NGSI-LD system as shown:

-
-

GET /ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22

-
-

Once again, the substitutions to make to the query string will depend on the rules of the natural language to be supported.

-

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

-

G.3.0 Foreword

-

Context data entities are designed to be interoperable and therefore all dates are held as UTC dates, all currency amounts are held as JSON numbers (with the unitCode property-of-a-property available to hold the currency), etc. Localization should not occur within the context data entities themselves. Offering fully localized responses is not a concern of the NGSI-LD API.

-

If localization support is necessary, a simple proxying a conversion mechanism could be used to amend the context data received from the NGSI-LD system before being passed to a third party system for display.

-

G.3.1 Localizing Dates

-

For example, if a system needs to display DateTime data in Islamic Date format

-

The following request on the proxy:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified

-
-

is forwarded unaltered and is sent to the NGSI-LD system as shown:

-
-

GET /ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified

-
-

The response from the NGSI-LD system is always in UTC format:

-

And the proxy can be used to update this to the desired format:

-

Using an internationalization script such as the following:

-
    {"date": "2020-09-28T17:13:39+02:00"}
-    {"date": "11 Safar, 1442 1:13:39PM"}
-new Intl.DateTimeFormat("en-u-ca-islamic", {day: 'numeric', month:
-'long',weekday: 'long',year : 'numeric'}).format(date);
-

It should be noted that post-localization, the transformed date is no longer valid NGSI-LD.

-
- - - - - diff --git a/API/2-foreword.html b/API/2-foreword.html deleted file mode 100644 index 525490fe813a05cc98f34332216fda64884569a3..0000000000000000000000000000000000000000 --- a/API/2-foreword.html +++ /dev/null @@ -1,1516 +0,0 @@ - - - - - - - -Foreword - - - - - - - - - - - - -
-

Foreword

-

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

-
- - - - - diff --git a/API/20-annex-h-informative-suggested-actuation-workflows.html b/API/20-annex-h-informative-suggested-actuation-workflows.html deleted file mode 100644 index f7e79ec08d69fd83e4ef8c0d865a06b3c4654ca3..0000000000000000000000000000000000000000 --- a/API/20-annex-h-informative-suggested-actuation-workflows.html +++ /dev/null @@ -1,1887 +0,0 @@ - - - - - - - -Annex H (informative): Suggested actuation workflows - - - - - - - - - - - - -
-

Annex H (informative): Suggested actuation workflows

-

H.1 Actuators and feedback to the consumer

-

Actuators are things that can change their state (light on/off) or execute actions (move forward, detect face, etc.).

-

There is currently no explicitly and precisely specified support for actuation in the NGSI-LD API. Thus, this clause describes some conventions that represent a proposed best-practice about how NGSI-LD API and data models can be used for the interaction between applications and actuators represented by NGSI-LD Entities.

-

The conventions and approach described in this clause are not powerful enough to implement complex actuation jobs that depend on each other and, for instance, make actuation decisions conditional on the outcome of other actuations, unless that behaviour is implemented in a custom way within the application logic. The concept of a more evolved service execution logic, being a first-class citizen of the NGSI-LD API and able to offer more structured building blocks for actuation, is outside the scope of this annex.

-

An NGSI-LD system that comprises an actuator and supports actuation workflows is represented as one or more NGSI-LD Entities, plus a Context Broker, a Context Source or a Context Producer, and a Context Consumer, which collaborate.

-

The interaction between actuator and Context Consumer needs to be bidirectional. Thus, actuators are triggered by the reception of actuation-specific commands (e.g. “set the on state of the lamp to false”, to turn the light off) that are encoded as NGSI-LD data, following a suggested data model. They respond with feedback, similarly encoded as NGSI-LD data.

-

Command feedbacks may serve to control the maximum operations rate a controlling application needs to achieve, and different levels of feedback can be requested, by associating a specific Quality of Service value to the command:

-
-
    -
  • Some applications need high operation rate but no feedback. For this case a QoS = 0 can be used. The typical example is to control the arms of a robot with a joystick.
    • -
  • Some applications need to be sure that the actuators actually received the command request or need to get back a payload in response to the command. In this case a QoS = 1 can be used. The typical case is switching on a light with confirmation, or request face-detection with consequent notification of matching events.
    • -
  • Commands can either require a short or a long execution time. For commands with long execution time, the application may require a continuous status feedback. In this case a QoS = 2 can be used. The typical example is that of a door opening, where feedback continuously report the current level (10 % open, 50 % open, etc.).
    • -
-
-

H.2 Architecture for actuation

-

In this architecture, the application acts as Context Consumer, and the terms are used interchangeably.

-

Commands are sent to the Context Broker by the Context Consumer, using the standard NGSI-LD API and a suggested convention for representing them. In turn, feedback about command execution is received by the Context Consumer, both as continuous status updates and/or a final command result.

-

More specifically, the component that handles direct communication with the actuator is the Context Source or the Context Producer: it uses an actuator-specific protocol to control the actuator and get responses and updates from it, i.e. from the real system. Such Context Source/Consumer or Context Producer/Storage acting as a proxy or intermediary to the actuator is referred to, in the following, as Context Adapter.

-

Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD command requests from the NGSI-LD Context Broker and send back command status and result to it, as well as using an actuator-specific protocol to communicate with the actuator.

-

The NGSI-LD Context Broker is responsible for handling direct communication with the Context Consumer.

-

Thus, to support actuation, there is a need to specify:

-
-
    -
  • Additional NGSI-LD Properties the NGSI-LD system has to have, in order to represent and manage command Request, Status, Result.
    • -
  • A communication model that allows commands to flow in forward direction and feedback to flow in reverse. This communication model has to comprise a mapping, to be held within the NGSI-LD system, that is able to route the command requests to the appropriate handler within the Context Adapter and vice-versa.
    • -
-
-
-

-
-
-

Figure H.2-1: Architecture for actuation

-
-

H.3 Structure of Commands and additional Properties

-

H.3.0 Introduction

-

The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing the actuator’s status, a set of additional, dedicated NGSI-LD Properties associated with:

-
-
    -
  • the list of available commands, i.e. the list of commands supported by the actuator;
    • -
  • command endpoints, one for each command, that are used to send and receive command related messages and optionally hold state for the ongoing commands.
    • -
-
-

The structure of the commands needs to be specified, but not the internal format of their payloads. By using commands with a custom payload, one can support all kinds of operations, for example:

-
-
    -
  • “set-on”: “true”
    • -
  • “detect-face”: {“face-features”: “….”}
    • -
  • “move”: “forward”
    • -
-
-

The data model for command requests, status and responses has to include metadata such as the QoS of the command, its identifier, and the custom payload itself.

-

Both the requests/responses and the list of commands the NGSI-LD system is able to support can be represented with additional NGSI-LD Properties, as follows.

-

H.3.1 Property for listing available commands

-

The additional Property dedicated to the list of available commands is as follows:

-
"commands": {
-  "type": "Property",
-  "value": ["`<cmd_name1>`","`<cmd_name2>`", …, "`<cmd_nameN>`"]
-}
-

It is a Property whose value is an array of Strings, each string representing the unique name of a supported command.

-

H.3.2 Properties for command endpoints

-

For each available command, a set of three endpoints is to be additionally created within the NGSI-LD system, by means of three dedicated Properties per command. The first endpoint will manage that command’s requests, the second endpoint will manage its status, and the third endpoint will manage command’s results.

-

This convention dictates that:

-
-
    -
  • The NGSI-LD Property that manages requests has the same name as the command, e.g. “<cmd_name1>”.
    • -
  • The NGSI-LD Property that manages results has the same name as the command plus the “-RESULT” suffix.
    • -
  • The NGSI-LD Property that manages status has the same name as the command plus the “-STATUS” suffix.
    • -
-
-

Each endpoint can receive multiple requests or responses, and it supports queueing of messages. For example, the command moveToLocation may receive a sequence of requests that are to be stored in an array and orderly processed depending on the arrival timestamps. A number of respective responses may be produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD Property, exploits the multi-Attribute feature (see clause 4.5.5), as follows:

-

Command Request endpoint

-

Command Status endpoint

-

Command Result endpoint

-
"`<cmd_name>`": {
-  "datasetId": a URI uniquely identifying the specific command request
-               (optional, if the use case does not need command queueing),
-  "type":      "Property",
-  "qos":       an Integer, representing the desired QoS (optional, default=0),
-  "value":     custom parameters of the command (mandatory)
-}
-"`<cmd_name>`-STATUS": {
-  "datasetId": a URI uniquely identifying the specific status feedback message
-               (optional, if the use case does not need queueing them),
-  "type":      "Property",
-  "value":     custom status of the command (mandatory)
-}
-"`<cmd_name>`-RESULT": {
-  "datasetId": a URI uniquely identifying the specific result feedback message
-               (optional, if the use case does not need queueing them),
-  "type":      "Property",
-  "value":     custom result of the command (mandatory)
-}
-

Usually, the Context Adapter (or the actuator behind it), upon receiving a command request with a specific datasetId, will then generate status and result with the same datasetId, so that, when the status/result is received by the application, it can link it back to the corresponding command that is generating the received feedback. The value of the request, status and result is generic, and it is up to the specific application to define useful values. As an example, the PackML language for the control of packaging machines defines a set of possible values for statuses during an actuation workflow.

-
-
-

EXAMPLE 1:

-
-
-

An example follows, where the NGSI-LD system represents a simple actuator. The example shows the NGSI-LD Entity representing a light that can change colour by manipulation of its brightness, hue and saturation values; further, it is possible to turn the lamp on and off. Apart from the id and the type , the actuator entity has a set of regular properties that represent the current status of the lamp. In the example these are colorRGB and is-on . Then it has the conventional Property named commands , signalling that it supports four commands: “turn-on” , “set-saturation” , “set-brightness” , “set-hue” . Further, it has four (times three) additional properties serving the purpose of command endpoints.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  REGULAR PROPERTIES
-  "colorRGB": {"type": "Property", "value": "0xABABAB"},
-  "is-on": {"type": "Property", "value": true},
-  AVAILABLE COMMANDS
-  "commands": {
-    "type": "Property",
-    "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"]
-  }
-  COMMAND ENDPOINTS
-  "turn-on": {"type": "Property", "value": `<custom request>`}
-  "turn-on-STATUS": {"type": "Property", "value": `<custom status>`}
-  "turn-on-RESULT": {"type": "Property", "value": `<custom response>`}
-  "set-hue": ...
-  "set-hue-STATUS": ...
-  "set-hue-RESULT": ...
-  …
-}
-
-
-
-
-

EXAMPLE 2:

-
-
-

The following example, shows an NGSI-LD Entity Fragment that can be used as a command request to request that the lamp be turned off.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  "turn-on": { 
-    "type": "Property",
-    "qos": {
-      "type": "Property",
-      "value": 1
-    },
-    "value": false
-  }
-}
-
-
-
-
-

EXAMPLE 3:

-
-
-

In the following example, the value of the command request is a more complex JSON Object, to show that complex actions can be conveyed by just one request. Further, the request has an identifier that makes it possible to enqueue it, together with other request that may arrive to the same command endpoint within a timespan.

-
{
-  "id": "urn:ngsi-ld:pHueActuator:light1",
-  "type": "Lamp",
-  "set-hue": { 
-    "type": "Property",
-    "qos": {
-      "type": "Property",
-      "value": 1
-    },
-    "datasetId": "myapp:mycommand:1342",
-    "value": {"red": "1 seconds", "green": "2 seconds"}
-  }
-}
-
-
-

In summary, the suggested convention prescribes a commands property that contains a list of commands supported by the actuator. For each of these commands, the convention requires a command endpoint consisting of three properties, the name of the command, e.g. “turn-on”, the status property, which is the name of the command with “-STATUS” as suffix, and the result, which is the name of the command with “-RESULT” as suffix. Nevertheless, it is noted that such suffixes are just a convention to distinguish the endpoints. So far, two practical implementations exist, see clauses H.5 and H.6, that adopt the general scheme of this convention, with minor deviations. In fact, this convention is derived as a generalization that leverages the full potential of NGSI-LD sub-Attributes and multi-Attributes.

-

H.4 Communication model

-

H.4.1 Possible communication models

-

This convention can be leveraged by two different communication models:

-
-
    -
  • Subscription/notification, where both the application and the Context Adapter use NGSI-LD Subscriptions to have the command requests delivered to the appropriate handler within the Context Adapter and vice-versa. In this case the Context Adapter acts as a Context Source as well as a Context Consumer.
    • -
  • Forwarding, which uses the NGSI-LD Registry and a Context Adapter able to federate itself with the Context Broker holding the actuator’s Entity, as a means to deliver the commands. In this case the Context Adapter acts as a Context Storage as well as a Context Producer.
    • -
-
-

H.4.2 Subscription/notification model

-

For the interaction to work, the Context Adapter, acting as a proxy to the actuator, subscribes to all command properties; in example 1 of clause H.3.2, these are “set-brightness”, “set-saturation”, “set-hue” and “turn-on”. When the application, acting as the actuation client, updates the value of a command property, the Context Adapter will receive the notification with the new value. This will be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol. The application in turn can subscribe to the command status and the result. The Context Adapter updates the status of the actuation during the execution of the command, which is primarily relevant in the case of longer-lasting actuations, and finally updates the result once the actuation has been completed. If the application has subscribed to the status and result, it will receive the corresponding notifications. Independent of the command-related properties, the status of the actuator, held within its regular properties, will be updated.

-

The detailed workflow is depicted in Figure H.4.2‑1, and can be interpreted as follows:

-
-
    -
  1. Application updates turn-on command Property with “value”: true
    2. -
  2. Context Adapter gets notification of the new value true
    3. -
  3. Context Adapter updates turn-on-STATUS command Property with “value”: “PENDING”
    4. -
  4. Application gets notification of the new value “PENDING”
    5. -
  5. Context Adapter updates is-on regular Property with “value”: true
    6. -
  6. Application gets notification with value: true
    7. -
  7. Context Adapter updates turn-on-RESULT command Property with “value”: “OK”
    8. -
  8. Application gets notification with of the new value “OK”
    9. -
-
-
-

-
-
-

Figure H.4.2-1: Steps of the actuation workflow using subscription/notification

-
-

H.4.3 Forwarding model

-

The forwarding model uses registrations and forwarding of requests. Actuation of commands is provisioned via registration(s) to the NGSI-LD Registry done by the Context Adapter that states “I am responsible for command property <X>”. When the Application changes the value of a command property, first the NGSI-LD Context Broker asks to the NGSI-LD Registry whether the property is delegated to some other component. The NGSI-LD Registry knows that property <X> of the Entity is delegated to the Context Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the other communication model, the request will then be translated into the proprietary format and forwarded to the actuator using the actuator-specific protocol.

-

In this model, the NGSI-LD Entity is distributed over two different components, because some of its properties live in the Context Brokers and other properties live in the Context Adapter, as indicated in Figure H.4.3‑1 with a dotted rectangle.

-

The rest of the workflow, i.e. delivery of status and result messages to the application, is done similarly to the subscription/notification model. The detailed workflow is depicted in Figure H.4.3‑1, and can be interpreted as follows:

-
-
    -
  1. Application updates turn-on command Property with “value”: true
    2. -
-
-
-

2a) Context Broker ask Registry where to forward the request

-
-
-

2b) Context Broker forwards request to Context Adapter

-
-
-
    -
  1. Context Adapter updates turn-on-STATUS command Property with “value”: “PENDING”
    2. -
-
-
-
    -
  1. Application gets notification of the new value “PENDING”
    2. -
-
-
-
    -
  1. Context Adapter updates is-on regular Property with “value”: true
    2. -
-
-
-
    -
  1. Application gets notification with value: true
    2. -
-
-
-
    -
  1. Context Adapter updates turn-on-RESULT command Property with “value”: “OK”
    2. -
-
-
-
    -
  1. Application gets notification with of the new value “OK”
    2. -
-
-
-

-
-
-

Figure H.4.3-1: Steps of the actuation workflow using forwarding

-
-

H.5 Implementation of the subscription-based actuation workflow

-

The Fed4IoT project (<https://fed4iot.org>) leverages the NGSI-LD architecture and the subscription/notification workflow for actuation, in order to implement the concept of a Cloud of Things. It enables virtualization of existing IoT sensors/actuators through Virtual Things and IoT Brokers. IoT application developers can simply rent the Virtual Things and the Brokers their applications need.

-

The Fed4IoT’s Cloud of Things is named VirIoT (<https://github.com/fed4iot/VirIoT>), and it is based on the concept of Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, NGSI-LD, etc.).

-

In Figure H.5‑1 a diagram shows how VirIoT implements the concept of a large-scale and distribute NGSI-LD system that leverages the architecture and the workflow convention described in clause H.4.2.

-
-

-
-
-

Figure H.5-1: VirIoT implementation of the NGSI-LD system and actuation workflow

-
-

All components encapsulate requests in a neutral-format message that leverages NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data distribution system, all information and actuation commands are encoded as NGSI-LD entities, plus an additional “meta header” that is used by the MQTT to publish and subscribe in a broadcast fashion to multiple vThings, because the same virtual sensor can be used by multiple applications at the same time.

-

For the actuation workflow, the “data” part of this message contains the command request, as specified in clause H.3, but with an additional value key that is the “command notification uri” (cmd-nuri), representing a location where feedback (status, result) should be sent by the ThingVisor. For example, the cmd-nuri contains the “data_in” MQTT topic of the issuing vSilo, so that command feedback (status and results) are sent to it, only, instead of being broadcasted to all subscribing applications.

-

VirIoT is agnostic to access control issues to a virtual actuator, since the relevant policies are implemented in the specific ThingVisor, which can grant tokens to execute actuation-commands to a subset of vSilos only, through preliminary exchange of specific actuation-commands (a kind of log-in).

-

Fed4IoT has developed several different ThingVisors (Context Adapters for different sensors and hardware): for example, lamp systems and robot devices are virtualized through specific ThingVisors, and applications can control the lighting system of a rented conference room or control camera and position of a bot by adding related virtual actuators to their vSilo.

-

H.6 Implementation of the registration-based actuation workflow

-

The IoT Agent node library [i.22] introduces the concept of an IoT Agent, which is a component that lets a group of devices send their data to and be managed from a Context Broker using their own native protocols. Thus, it corresponds to the Context Adapter, and wires up the IoT devices so that measurements can be read and commands can be sent using NGSI-LD requests sent to an NGSI-LD compliant context Context Broker.

-

IoT Agents already exist or are in development for many IoT communication protocols and data models. Examples include the following:

-
-
    -
  • IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON payload) and NGSI-LD
    • -
  • IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and NGSI-LD
    • -
  • IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an UltraLight2.0 payload) and NGSI-LD
    • -
  • IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD
    • -
-
-

This implementation follows the communication model described in clause H.4.3, as explained in Figure H.6‑1. In this workflow:

-
-
    -
  • Requests between User and Context Broker use NGSI-LD
    • -
  • Requests between Context Broker and IoT Agent use NGSI-LD
    • -
  • Requests between IoT Agent and IoT Device use native protocols
    • -
  • Requests between IoT Device and IoT Agent use native protocols
    • -
  • Requests between IoT Agent and Context Broker use NGSI-LD
    • -
-
-
-

-
-
-

Figure H.6-1: IoT Agent node library implementation of the NGSI-LD system and actuation workflow

-
-

Provisioning of the devices will be carried out (via REST API) through IoT Agents, as well. This provisioning implies that, on the one hand, the corresponding entities (with their commands), that represent the devices, are generated in the Context Broker and, on the other hand, that the corresponding IoT Agent is configured for communication with the corresponding device, all in one provisioning step. Below, an example how to provision a device which supports start and stop commands is presented.

-
{
-    "devices": [
-        {
-            "device_id":   "device001",
-            "entity_name": "urn:ngsi-ld:Device:001",
-            "entity_type": "Device",
-            "attributes": [
-                { "object_id": "s", "name": "isOpen", "type": "boolean" }
-            ],
-            "commands": [
-                { "name": "start", "type": "command" },
-                { "name": "stop", "type": "command" }
-            ],
-            "static_attributes": [
-                { "name":
-                    { "type": "Text", "value": "Device:001 provision" }
-                }
-            ]
-        }
-    ]
-}
-
- - - - - diff --git a/API/21-annex-i-informative-change-history.html b/API/21-annex-i-informative-change-history.html deleted file mode 100644 index 9749d83f23ebfe24e15f1553d6ab1968d21ef544..0000000000000000000000000000000000000000 --- a/API/21-annex-i-informative-change-history.html +++ /dev/null @@ -1,2694 +0,0 @@ - - - - - - - -Annex I (informative): Change history - - - - - - - - - - - - -
-

Annex I (informative): Change history

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Date -
-Version -
-Information about changes -
-February 2020 -
-

1.2.10

-
-Early draft copied from API version 1.2.1 -
-February 2020 -
-

1.2.11

-
-

Unicode characters. Query Language syntax changes to Attribute path, and extension to accept specifying just Query or Geoquery when Querying Entities

-

Acknowledgements to EU projects. Lightweight Figures

-
-March 2020 -
-

1.2.12

-
-

Extending to other interactions the above changes to query entities interaction

-

Changes to ABNF Query Language syntax to access complex objects value of properties more easily

-

Generalized Notification Headers, in order to carry authentication etc., info

-

Novel &option=count and associated Header to indicate number of Entities in response to a query

-

Novel/entityOperations/query and/temporal/entityOperations/query endpoints to perform query via POST

-

Clarified attrs URL parameter behaviour

-

Support for Multiple Attributes

-

Support for Multiple Tenants

-
-May 2020 -
-

Candidate 1.2.13

-
-

from 101r1: Multi-Attribute-Support-fix-in-4.5.5

-

from 102r1: Batch_Operation_Error_Codes

-

from 110r1: JSON-LD Validation clause

-

from 112r1: IRI Support for International Characters

-

from 115r2: More Core Context Changes

-

from 130: Entity Types

-

MQTT Notifications

-

GeoJSON Representation

-
-9 July 2020 -
-

1.3.1

-
-Technical Officer verifications for submission to editHelp! publication pre-processing -
-August 2020 -
-

1.3.2

-
-New baseline towards v1.4.1 -
-November 2020 -
-

1.3.3

-
-From 272r1: Support for natural languages via LanguageProperty; annex G -
-December 2020 -
-

1.3.4

-
-From 319: Align Table 6.8.3.2‑1 with clause 5.10.2 for query via attrs -
-December 2020 -
-

1.3.4

-
-From 310r2: Dot vs. comma in DateTime -
-December 2020 -
-

1.3.4

-
-From 309r1: Remove sentences referring to old multi attributes representation -
-December 2020 -
-

1.3.4

-
-From 308r: id and type for JSON-LD compliance -
-December 2020 -
-

1.3.4

-
-

From 313r1: FIXES to Cross domain data model for LanguageProperties

-

Bug fixes and errata

-
-December 2020 -
-

1.3.5

-
-From 275r3: Temporal Aggregation Functions -
-December 2020 -
-

1.4.0

-
-1.3.5 with small typos corrected, approved as 1.4.0 -
-January 2021 -
-

1.4.1

-
-ETSI Technical Officer review for ETSI EditHelp publication pre-processing -
-March 2021 -
-

1.4.2

-
-Editorial Changes, clarifications added, better references, figures replacements and corrections, figures merged, typos, code identation -
-April 2021 -
-

1.4.2

-
-Temporal Pagination -
-April 2021 -
-

1.4.2

-
-Clarified behavior when multiple instances of the same Entity are in an input array -
-July 2021 -
-

1.4.3

-
-From 130r6: NGSI-LD Scope -
-July 2021 -
-

1.4.3

-
-From 143r6: Storing, managing and serving @contexts -
-July 2021 -
-

1.4.3

-
-From 120r4: API structuring -
-October 2021 -
-

1.4.4

-
-From 156: Remove static elements from temporal representations -
-October 2021 -
-

1.4.4

-
-From 155: Existence query -
-October 2021 -
-

1.4.4

-
-From 152: Remove null value deletion -
-October 2021 -
-

1.4.4

-
-From 151: attrs missing in core context -
-October 2021 -
-

1.5.1

-
-ETSI Technical Officer review for ETSI EditHelp publication pre-processing -
-November 2021 -
-

1.5.2

-
-First early draft after EditHelp publication of V1.5.1 to prepare next V1.6.1 publication -
-January 2022 -
-

1.5.3

-
-Concise representation -
-May 2022 -
-

1.5.4

-
-PUT/PATCH Entity -
-May 2022 -
-

1.5.4

-
-Distributed operations -
-July 2022 -
-

1.5.5

-
-From 99r6: Deletions and advanced notifications -
-July 2022 -
-

1.5.5

-
-From 106r1: Workflow for actuation -
-July 2022 -
-

1.5.5

-
-From 105r1: Context Source Info in Context Source Registration -
-July 2022 -
-

1.5.5

-
-From 93r1: default context clarification -
-July 2022 -
-

1.5.5

-
-From 91r1: CR_on_Scope_ABNF_format -
-Juy 2022 -
-

1.6.1

-
-Final Technical Official check for EditHelp publication -
-October 2022 -
-

1.6.2

-
-

New early draft:

-

corrected Annex C6 date representation

-

from 149r3: generalized description of @context in bullet lists

-

Fixed usage of NGSI-LD Null in Attributes’ definitions

-
-December 2022 -
-

1.6.4

-
-From 188r2_Registration_Clarifications -
-December 2022 -
-

1.6.4

-
-From 182r2_Add_NGSI-LD_Roles_for_Context_Registration -
-December 2022 -
-

1.6.4

-
-From 156r2 VocabProperty/URI type coercion -
-December 2022 -
-

1.6.4

-
-177r2 Clarify usage of Accept, Content-Type and Linked @context when forwarding to partial Context Brokers -
-December 2022 -
-

1.6.4

-
-178 Add Batch Query to Federation Ops -
-December 2022 -
-

1.6.4

-
-183r1 Clarify Temporal query behaviour -
-December 2022 -
-

1.6.4

-
-149r4 Forbid scoped and nested @contexts -
-December 2022 -
-

1.6.4

-
-023006 Fixing CSource registration example in C.3 -
-December 2022 -
-

1.6.4

-
-Fix: Tenants URI becomes String -
-December 2022 -
-

1.6.4

-
-Fix: POST-QUERY-COUNT-PAGINATION -
-December 2022 -
-

1.6.4

-
-Fix: CHECK-URI-PARAM -
-December 2022 -
-

1.6.4

-
-Updated examples and text to context v1.7.jsonld -
-March 2023 -
-

1.6.6

-
-CIM(23)000006_Adding_previousValue_to_GeoProperty_type_definition -
-March 2023 -
-

1.6.6

-
-cSource -> CSource; “implementations shall do the following” -
-March 2023 -
-

1.6.7

-
-000013r4_Updated_Distributed_Execution_Behaviour -
-March 2023 -
-

1.6.8

-
-CIM(22)000195r3_type_passing_for_M2M_callReviewed -
-April 2023 -
-

1.6.9

-
-Fixing URI🡪String datatypes -
-June 2023 -
-

1.7.2

-
-CIM(23)000053r1_Entity_Graph_Retrieval (for FIWARE SUMMIT) -
-June 2023 -
-

1.7.3

-
-000056r2_APIv172_towards_v18.docx (for FIWARE SUMMIT) -
-October 2023 -
-

1.7.4

-
-From 25023r2: Use Temporal Evolution instead of Temporal Representation + Updated figures in clause 5 and 6 -
-November 2023 -
-

1.7.5

-
-

From 68r5: Additional id only format and attribute projection via pick and omit

-

From 121r1: Relationship as Array

-

From 123r1: URN Namespace Definitions

-

From 149r3: Allow Broader Local Requests

-

From 153r1: JsonProperty

-

From 159: Bug fixed in CIM 009: GeoJSON responses in figures

-

From 160: Replace Attribute fix

-
-December 2023 -
-

1.7.6

-
-

From 164: Host alias /info Endpoint

-

From 154r2: EntityMap

-

Updated figure in clause 6.2

-
-January 2024 -
-

1.7.7

-
-

From 168r1: 504 error instead of 503 in JSON-LD context endpoints

-

From 169r1: Allow forbidden characters

-

From 170: Remove Scope from PATCH /attrs operations

-

From 1005r2: URI for value of several attributes

-

From 173r2: Clarify match in distributed operations

-

From 174: Protect core context

-

From 25002r2: API Issue #10 Filter on value with specific datasetId

-
-January 2024 -
-

1.7.8

-
-

From 164r5: fix Tenant in Host Alias (164) and /info/sourceIdentity Endpoint + figure

-

Updated figure in clause 6.2

-

Updated figures in clause 4.2

-
-January 2024 -
-

1.7.9

-
-CIM(24)000007r2_Query_Language_Extension_for_Linked_Entity_Retrieval -
-January 2024 -
-

1.7.10

-
-Internal revision, cleanup -
-January 2024 -
-

1.7.10

-
-FIX: CIM(24)000015_Projection_attributes_error_messaging -
-January 2024 -
-

1.7.10

-
-FIX: CIM(24)000014r1_POST_Query_Parameters -
-January 2024 -
-

1.7.11

-
-TO revision -
-January 2024 -
-

1.7.12

-
-ISG CIM revision and cleanup after TO revision. New keywords -
-February 2024 -
-

1.7.13

-
-Footnotes in Tables -
-February 2024 -
-

1.7.15

-
-Change of NGSILDTerm style to HTML Keyboard -
-February 2024 -
-

1.7.16

-
-Added expiresAt to @context serving -
-March 2024 -
-

1.8.1

-
-Published -
-April 2024 -
-

1.8.2

-
-Clone of published -
-April 2024 -
-

1.8.3

-
-Minor typos and style cleanup -
-April 2024 -
-

1.8.3

-
-000048_Fix_operations_allowing_sysAttrs.docx -
-April 2024 -
-

1.8.3

-
-000047r2_Accept_header_in_case_of_partial_success__207_.docx -
-April 2024 -
-

1.8.3

-
-000049r1_Clarify__options__allowed_for_POST_queries.docx -
-April 2024 -
-

1.8.4

-
-Track changes removed -
-May 2024 -
-

1.8.5

-
-TooLargeResponse -
-June 2024 -
-

1.8.6

-
-CIM(24)000036r1_Loop_Detection -
-June 2024 -
-

1.8.7

-
-CIM(24)000033r6_Backwards_Compatibility_Indicators -
-June 2024 -
-

1.8.8

-
-CIM(24)000027r5_Value_Type -
-June 2024 -
-

1.8.9

-
-CIM(24)000029_Purge_Entities -
-June 2024 -
-

1.8.10

-
-CIM(24)000028r4_Transient_Entity_bugfixed -
-June 2024 -
-

1.8.11

-
-CIM(24)000070_Additional_Updates_to_ExpiresAt__Conformance_etc_ -
-October 2024 -
-

1.8.12

-
-CIM(24)000076r8_Entity_Maps_and_Split_Entities -
-October 2024 -
-

1.8.13

-
-CIM(24)000108_Adding_Missing_Elements_in_Core_Context_and_Data_Types.zip -
-October 2024 -
-

1.8.14

-
-Updated figures and new baseline and created Stable Draft out of this -
-November 2024 -
-

1.8.15

-
-CIM(24)000128r1_Signed_Attributes_and_Scoped_Context -
-December 2024 -
-

1.8.16

-
-VocabProperty instead of VocabularyProperty in C2.2 and Table 5.2.35‑1 -
-January 2025 -
-

1.8.17

-
-Reordering table rows in alpha (almost) order -
-January 2025 -
-

1.8.18

-
-Ngsildproof example and @context. Switching to new @context URI for v1.9 -
-February 2025 -
-

1.8.19

-
-CIM(25)000005 temporal bounds _clarifications_and_misc_fixes -
-March 2025 -
-

1.8.20

-
-CIM(24)000111r5_Ordered_Entites -
-March 2025 -
-

1.8.21

-
-CIM(24)000138r4_Snapshot -
-March 2025 -
-

1.8.22

-
-CLEAN. Removed all track changes. Comments to be still addressed -
-March 2025 -
-

1.8.23

-
-CIM(25)000011r1 Updated figures and text for Snapshots (clauses 5 and 6) -
-March 2025 -
-

1.8.24

-
-CIM(25)000012r1 Harmonize output and 203 -
-April 2025 -
-

1.8.25

-
-CIM(25)000014 GS_CIM_009_v1825_fixSubscriptions -
-April 2025 -
-

1.8.26

-
-CIM(25)000016 Explaination of valueType as data type -
-April 2025 -
-

1.8.27

-
-CIM(25)000015 Precision Clarification + Harmonize captions in clause 6 + addressing fixes requested in the comments -
-May 2025 -
-

1.8.28

-
-CIM(25)000023 Order Table rows + small editorial fixes + aggregation parmeters for POST query -
-May 2025 -
-

1.8.29

-
-Final review prior to EditHelp -
-
- - - - - diff --git a/API/22-history.html b/API/22-history.html deleted file mode 100644 index 9609e355d8743a9b986ab27110b538273ae20686..0000000000000000000000000000000000000000 --- a/API/22-history.html +++ /dev/null @@ -1,1639 +0,0 @@ - - - - - - - -History - - - - - - - - - - - - -
-

History

- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Document history -
-V1.1.1 -
-January 2019 -
-Publication -
-V1.2.1 -
-October 2019 -
-Publication -
-V1.2.2 -
-February 2020 -
-Publication -
-V1.3.1 -
-August 2020 -
-Publication -
-V1.4.1 -
-February 2021 -
-Publication -
-V1.4.2 -
-April 2021 -
-Publication -
-V1.5.1 -
-November 2021 -
-Publication -
-V1.6.1 -
-August 2022 -
-Publication -
-V1.7.1 -
-June 2023 -
-Publication -
-V1.8.1 -
-March 2024 -
-Publication -
-
- - - - - diff --git a/API/3-modal-verbs-terminology.html b/API/3-modal-verbs-terminology.html deleted file mode 100644 index f2b65bc7177dd1e6ec54e89ce3e246308a2d2e27..0000000000000000000000000000000000000000 --- a/API/3-modal-verbs-terminology.html +++ /dev/null @@ -1,1517 +0,0 @@ - - - - - - - -Modal verbs terminology - - - - - - - - - - - - -
-

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.

-
- - - - - diff --git a/API/4-executive-summary.html b/API/4-executive-summary.html deleted file mode 100644 index 622b7c02d6278b06269dd91ad5dc26871db03c6c..0000000000000000000000000000000000000000 --- a/API/4-executive-summary.html +++ /dev/null @@ -1,1516 +0,0 @@ - - - - - - - -Executive summary - - - - - - - - - - - - -
-

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

-
- - - - - diff --git a/API/5-introduction.html b/API/5-introduction.html deleted file mode 100644 index 759277a83997f7ae9cb14df2c5cd3ccc9ac4e19e..0000000000000000000000000000000000000000 --- a/API/5-introduction.html +++ /dev/null @@ -1,1519 +0,0 @@ - - - - - - - -Introduction - - - - - - - - - - - - -
-

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.

-
- - - - - diff --git a/API/6-tabscope.html b/API/6-tabscope.html deleted file mode 100644 index f7a709f72728111bdfefd4110654bfbdfd1ff29b..0000000000000000000000000000000000000000 --- a/API/6-tabscope.html +++ /dev/null @@ -1,1516 +0,0 @@ - - - - - - - -1 Scope - - - - - - - - - - - - -
-

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

-
- - - - - diff --git a/API/7-tabreferences.html b/API/7-tabreferences.html deleted file mode 100644 index 2149e428918e0c8a233876af797f72eb06ef4870..0000000000000000000000000000000000000000 --- a/API/7-tabreferences.html +++ /dev/null @@ -1,1728 +0,0 @@ - - - - - - - -2 References - - - - - - - - - - - - -
-

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

-
-
-

NOTE:

-
-
-

While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity.

-
-
-

The following referenced documents are necessary for the application of the present document.

-
[1] W3C -® - Recommendation 25 February 2014: “ -RDF Schema 1.1 -”. -
[2] W3C -® - Recommendation 16 July 2020: “ -JSON-LD 1.1 - A JSON-based Serialization for Linked Data -”. -
[3] -IETF RFC 7231 -: “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”. -
[4] -IETF RFC 7232 -: “Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests”. -
[5] -IETF RFC 3986 -: “Uniform Resource Identifier (URI): Generic Syntax”. -
[6] -IETF RFC 8259 -: “The JavaScript Object Notation (JSON) Data Interchange Format”. -
[7] -IETF RFC 8288 -: “Web Linking”. -
[8] -IETF RFC 7946 -: “The GeoJSON Format”. -
[9] -IETF RFC 8141 -: “Uniform Resource Names (URNs)”. -
[10] -IETF RFC 7807 -: “Problem Details for HTTP APIs”. -
[11] -IEEE 1003.2™-1992 -: “IEEE Standard for Information Technology - Portable Operating System Interfaces (POSIX™) - Part 2: Shell and Utilities”. -
[12] -IETF RFC 5234 -: “Augmented BNF for Syntax Specifications: ABNF”. -
[13] -Unicode® Technical Standard #10 -: “Unicode Collation Algorithm”. -
[14] -Open Geospatial Consortium Inc. OGC 06-103r4 -: “OpenGIS -® - Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture”. -
[16] -IETF RFC 7396 -: “JSON Merge Patch”. -
[17] -ISO 8601: 2019 -: “Data elements and interchange formats -- Information interchange -- Representation of dates and times”. -
[18] -IETF RFC 2818 -: “HTTP Over TLS”. -
[19] -IETF RFC 5246 -: “The Transport Layer Security (TLS) Protocol Version 1.2”. -
[21] -ECMA 262 Specification -: “ECMAScript -® - 2022 language specification”. -
[22] The Unicode Consortium: “ -Unicode® 15.0.0 -“. -
[23] -IETF RFC 3987 -: “Internationalized Resource Identifiers (IRIs)”. -
[24] OASIS Standard: “ -MQTT Version 3.1.1 Plus Errata 01 -”. Edited by Andrew Banks and Rahul Gupta. 10 December 2015. -
[25] OASIS Standard: “ -MQTT Version 5.0 -”. Edited by Andrew Banks, Ed Briggs, Ken Borgendale and Rahul Gupta. 07 March 2019. -
[26] -IETF RFC 7240 -: “Prefer Header for HTTP”. -
[27] -IETF RFC 7230 -: “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”. -
[28] -IETF RFC 5646 -: “Tags for Identifying Languages”. -
[29] -IETF RFC 3282 -: “Content Language Headers”. -
[30] -IETF RFC 7234 -: “Hypertext Transfer Protocol (HTTP/1.1): Caching”. -
[31] -IETF RFC 7233 -: “Hypertext Transfer Protocol (HTTP/1.1): Range Requests”. -
[33] -IETF RFC 6906 -: “The ‘profile’ Link Relation Type”. -
[34] W3C -® - Recommendation 25 February 2014: “ -RDF 1.1 Concepts and Abstract Syntax -”. -
[35] -ETSI GS CIM 019 -: “cross-cutting Context Information Management (CIM); handling of provenance information in NGSI-LD”. -
[36] -IETF RFC 6067 -: “BCP 47 Extension U”. -
[37] -ETSI GS CIM 047 -: “Context Information Management (CIM); OpenAPI Specification for NGSI-LD API”. -
-

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.

-
-
-

NOTE:

-
-
-

While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee their long-term validity.

-
-
-

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.

-
[i.1] -ETSI GR CIM 002 (V1.1.1) -: “Context Information Management (CIM); Use Cases (UC)”. -
[i.2] -ETSI GR CIM 007 -: “Context Information Management (CIM); Security and Privacy”. -
[i.3] -OMA-TS-NGSI_Context_Management-V1_0-20120529-A -: “NGSI Context Management”. -
[i.4] ETSI TS 103 264 (V3.1.1): “SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping”. -
[i.5] -NGSI-LD Wrapper -. - Experimental proxy for adaptation between FIWARE -® - and NGSI-LD. -
[i.6] Graph Databases: “New Opportunities for Connected Data”. O’Reilly 2 -nd - Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892. -
[i.7] -JSON-LD Playground -. -Experimentation tool for JSON-LD. -
[i.8] -ETSI GS CIM 006 -: “Context Information Management (CIM); Information Model (MOD0)”. -
[i.10] -IETF RFC 6902 -: “JavaScript Object Notation (JSON) Patch”. -
[i.16] ETSI GS CIM 004 (V1.1.2): “Context Information Management (CIM); Application Programming Interface (API)”. -
[i.17] ETSI ISG CIM: “ -NGSI-LD Status -”. -
[i.18] -Regulation (EU) 2016/679 - of the European Parliament and of the Council of 27 April 2016 on the protection of natural persons with regard to the processing of personal data and on the free movement of such data, and repealing Directive 95/46/EC (General Data Protection Regulation). -
[i.20] -GeoJSON-LD 1.0 -. -Base context for processing GeoJSON according to the JSON-LD processing model. -
[i.21] -ETSI GR CIM 008 -: “Context Information Management (CIM); NGSI-LD Primer”. -
-
- - - - - diff --git a/API/8-tabdefinition-of-terms-symbols-and-abbreviations.html b/API/8-tabdefinition-of-terms-symbols-and-abbreviations.html deleted file mode 100644 index 7ff42322f034fe9c21c6ddf717b2698cb4cc0bec..0000000000000000000000000000000000000000 --- a/API/8-tabdefinition-of-terms-symbols-and-abbreviations.html +++ /dev/null @@ -1,1782 +0,0 @@ - - - - - - - -3 Definition of terms, symbols and abbreviations - - - - - - - - - - - - -
-

3 Definition of terms, symbols and abbreviations

-

3.1 Terms

-

For the purposes of the present document, the following terms apply:

-
-
-

NOTE 1:

-
-
-

The letters “NGSI-LD” were added to most terms to confirm that they are distinct from other terms of similar/same name in use in other organizations, however, in the present document the letters “NGSI-LD” are generally omitted for brevity.

-
-
-
-
-

NOTE 2:

-
-
-

The use of URI in the context of the present document also includes the use of International Resource Identifiers (IRIs) as defined in IETF RFC 3987 [23], which extends the use of characters to Unicode characters [22] beyond the ASCII character set, enabling the support of languages other than English.

-
-
-

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

-
-
-

NOTE:

-
-
-

It is used by Distribution Brokers and Federation Brokers to find the appropriate Context Sources which can provide the information required for serving an NGSI-LD request.

-
-
-

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

-
-
-

NOTE:

-
-
-

It is usually registered with an NGSI-LD Registry so that it can announce what kind of information it can provide, when requested, to Context Consumers and Brokers.

-
-
-

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

-
-
-

NOTE:

-
-
-

In the NGSI-LD API, any instance of such an entity is uniquely identified by a URI , and characterized by reference to one or more NGSI-LD Entity Type(s) .

-
-
-

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 Entity Type: categorization of an NGSI-LD Entity as belonging to a class of similar entities, or sharing a set of characteristic properties

-
-
-

NOTE:

-
-
-

In the NGSI-LD API, an NGSI-LD Entity Type is uniquely identified by a URI .

-
-
-
-
-

EXAMPLE 1:

-
-
-

“Vehicle” is an NGSI-LD Entity Type and is identified with a proper URI.

-
-
-
-
-

EXAMPLE 2:

-
-
-

Bob’s private car whose plate number is “ABCD1234” is an NGSI-LD Entity whose NGSI-LD Entity Type name is “Vehicle”.

-
-
-
-
-

EXAMPLE 3:

-
-
-

Alice’s motorhome has a unique URI as id, but can be assigned multiple NGSI-LD Entity types, e.g. “Vehicle” and “Home” .

-
-
-

NGSI-LD External Linked Entity: Linked Entity that is identified through a dereferenceable URI which does not exist within the current NGSI-LD system

-
-
-

NOTE:

-
-
-

It can exist within another NGSI-LD system or within a non-NGSI-LD system.

-
-
-
-
-

EXAMPLE:

-
-
-

An NGSI-LD Entity, whose Entity Type name is “Book” , can be externally linked, through the “wasWrittenBy” relationship, to a resource identified by the URI “http://dbpedia.org/resource/Mark_Twain” .

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

An NGSI-LD Entity, whose Entity Type name is “Vehicle”, can be internally linked, through the “isParkedAt” relationship, to another NGSI-LD Entity, of Type name “Parking” , identified by the URI “urn:ngsi-ld:Parking:Downtown1” .

-
-
-

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

-
-
-

NOTE:

-
-
-

The target value contains data which is not available for interpretation.

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“A bus route services the following bus stops” can be represented by an NGSI-LD ListRelationship whose name is “route” which holds an array of directed links towards a series of NGSI-LD Entities of type (Type name) “BusStop” .

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s vehicle is currently parked on a street which is known as ‘Grand Place’ in French and ‘Grote Markt’ in Dutch” can be represented by an NGSI-LD LanguageProperty whose name is “street” which holds an NGSI-LD Map of two key-value pairs containing both the French (“fr” ) and Dutch ( “nl” ) exonyms of the street name.

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s vehicle’s speed is 40 km/h” can be represented by an NGSI-LD Property, whose name is “speed”, and which characterizes an NGSI-LD Entity, whose NGSI-LD Type is “Vehicle” . Such a name can be expanded to a fully qualified name in the form of a URI , for instance “http://example.org/Vehicle” or “http://example.org/speed” .

-
-
-

NGSI-LD Query: collection of criteria used to select a sub-set of NGSI-LD Elements, 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

-
-
-

EXAMPLE 1:

-
-
-

An NGSI-LD Entity of type “Vehicle” can be the subject of an NGSI-LD Relationship whose object is an NGSI-LD Entity of type “Parking” .

-
-
-
-
-

EXAMPLE 2:

-
-
-

An NGSI-LD Entity of type “Vehicle” can be the subject of an NGSI-LD Relationship whose object is an array of NGSI-LD Entities of type “Passenger” .

-
-
-

NGSI-LD Scope: hierarchical structuring of Entities that enables restricting query results and notifications

-

NGSI-LD Snapshot: set of NGSI-LD Entities, retrieved through one or more NGSI-LD Queries, which are locally persisted, providing a relatively consistent view of the situation when the queries were executed, and on which Context Consumers can execute further local NGSI-LD Operations

-

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)

-
-
-

EXAMPLE:

-
-
-

Bob’s private car ‘speed’ NGSI-LD Value is the number 100 (kilometres per hour).

-
-
-

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

-
-
-

EXAMPLE:

-
-
-

“Bob’s car is a non-commercial vehicle” can be represented by an NGSI-LD VocabProperty whose name is “category” which holds the string value “non-commercial” . If the associated JSON-LD context defines the term “non-commercial” as “http://example.com/non-commercial”, then the returned value shall be expanded using JSON-LD type coercion into the URI the “http://example.com/non-commercial” .

-
-
-

3.2 Symbols

-

Void.

-

3.3 Abbreviations

-

For the purposes of the present document, the following abbreviations apply:

- -
ABNF
Augmented Backus-Naur Form
-
ALG1
Algorithm for transforming an NGSI-LD Entity into a JSON-LD document
-
AM
Ante Meridiem
-
API
Application Programming Interface
-
ASCII
American Standard Code for Information Interchange
-
BNF
Backus Naur Form
-
CH
Switzerland
-
CSR
Context Source Registration
-
ECMA
European Computer Manufacturers Association
-
EU
European Union
-
FI
Future Internet
-
FQN
Fully Qualified Name
-
GB
Great Britain
-
GDPR
General Data Protection Regulation
-
GeoJSON
Geographic JavaScript Object Notation
-
GeoJSON-LD
Geographic JavaScript Object Notation - Linked Data
-
GIS
Geographic Information System
-
GPS
Global Positioning System
-
HTTP
Hypertext Transfer Protocol
-
HTTPS
Hypertext Transfer Protocol Secure
-
IANA
Internet Assigned Numbers Authority
-
ID
Identifier
-
IEEE
Institute of Electrical and Electronics Engineers
-
IETF
Internet Engineering Task Force
-
IoT
Internet of Things
-
IRI
Internationalized Resource Identifier
-
ISG
Industry Specification Group
-
ISO
International Organization for Standardization
-
JSON
JavaScript Object Notation
-
JSON-LD
JSON Linked Data
-
LD
Linked Data
-
LWM2M
LightWeight Machine to Machine
-
M2M
Machine to Machine
-
MIME
Multi-purpose Internet Mail Extensions
-
MQTT
Message Queuing Telemetry Transport
-
N/A
Not Applicable
-
NGSI
Next Generation Service Interfaces
-
NGSILD
Next Generation Service Interfaces Linked Data (same as NGSI-LD)
-
NID
Namespace Identifier
-
NSS
Namespace Specific String
-
OAS
Open API Specification
-
OMA
Open Mobile Alliance
-
oneM2M
oneM2M Partnership Project
-
PM
Post Meridiem
-
POSIX
Portable Operating System Interface
-
QoS
Quality of Service
-
RDF
Resource Description Format
-
REST
Representational State Transfer
-
RFC
Request For Comments
-
SAREF
Smart Applications REFerence ontology
-
TCP
Transport Control Protocol
-
TLS
Transport Layer Security
-
TS
Technical Specification
-
UCA
Unicode Collation Algorithm
-
UL
Ultra Light
-
UML
Unified Modelling Language
-
URI
Uniform Resource Identifier
-
URL
Universal Resource Locator
-
URN
Uniform Resource Name
-
UTC
Coordinated Universal Time
-
UTF
Unicode (or Universal Coded Character Set) Transformation Format
-
- - - - - diff --git a/API/9-tabcontext-information-management-framework.html b/API/9-tabcontext-information-management-framework.html deleted file mode 100644 index bf6397ff5c3b204d9ec7bfcbb2fc35acdfa5389b..0000000000000000000000000000000000000000 --- a/API/9-tabcontext-information-management-framework.html +++ /dev/null @@ -1,7039 +0,0 @@ - - - - - - - -4 Context Information Management Framework - - - - - - - - - - - - -
-

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.

-
-

-
-
-

Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure

-
-

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.

-
-

-
-
-

Legend:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-

-
-

[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.2-1: NGSI-LD Core Meta-Model

-
-

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

-
-

-
-
-

Legend:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - -
-

-
-

[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: NGSI-LD Core Meta-Model plus the Cross-Domain 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”.

-
-

-
-
-

Figure 4.2.4-1: Cross-Domain Ontology and instantiation

-
-

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.

-
-

-
-
-

Figure 4.2.5-1: NGSI-LD information model as UML

-
-

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 NGSI-LD API implicitly defines two sets of Entities:

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

-
-

-
-
-

Figure 4.3.2-1: Centralized architecture

-
-

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.

-
-

-
-
-

Figure 4.3.3-1: Distributed architecture

-
-

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.

-
-

-
-
-

Figure 4.3.4-1: Federated architecture

-
-

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. To support the distributed and federated architectures described in clauses 4.3.3 and 4.3.4 respectively, distributed versions of the operations are needed. They are listed separately under Distributed API and require the operations of the Registry API. 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. The distributed versions of the operations are separately shown in Table 4.3.5‑1 under Distributed API, but there is a single clause for each of the operations describing both the centralized and distributed behaviour. In addition, the Distributed API has support operations only needed in distributed and federated architectures.

-
-

Table 4.3.5-1: NGSI-LD API structure

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-API -
-Functionality -
-Operations -
-

Core API

-
-

Context Information Provision - operations for providing or managing Entities and Attributes

-
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-
-Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system -
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-
-Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions -
-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.8.6 Notification

-
-

Temporal API

-
-Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entitiesand Attributes -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities -
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-
-Distributed API -
-Distributed Context Information Provision –operations for providing or managing Entities and Attributes -
-

5.6.1 Create Entity(distributed)

-

5.6.2 Update Attributes(distributed)

-

5.6.3 Append Attributes(distributed)

-

5.6.4 Partial Attribute Update(distributed)

-

5.6.5 Delete Attribute(distributed)

-

5.6.6 Delete Entity(distributed)

-

5.6.7 Batch Entity Creation(distributed)

-

5.6.8 Batch Entity Upsert(distributed)

-

5.6.9 Batch Entity Update(distributed)

-

5.6.10 Batch Entity Delete(distributed)

-

5.6.17 Merge Entity(distributed)

-

5.6.18 Replace Entity(distributed)

-

5.6.19 Replace Attribute(distributed)

-

5.6.20 Batch Entity Merge(distributed)

-
-Distributed Context Information Consumption - operations for consuming Entities and checking for which Entity Types and Attributes Entities are available in the system -
-

5.7.1 Retrieve Entity(distributed)

-

5.7.2 Query Entities(distributed)

-

5.7.5 Retrieve Available Entity Types(distributed)

-

5.7.6 Retrieve Details of Available Entity Types(distributed)

-

5.7.7 Retrieve Available Entity Type Information(distributed)

-

5.7.8 Retrieve Available Attributes(distributed)

-

5.7.9 Retrieve Details of Available Attributes(distributed)

-

5.7.10 Retrieve Available Attribute Information(distributed)

-
-Distributed Context Information Subscription - operations for subscribing to Entities, receiving notifications and managing subscriptions -
-

5.8.1 Create Subscription(distributed)

-

5.8.2 Update Subscription(distributed)

-

5.8.3 Retrieve Subscription(distributed)

-

5.8.4 Query Subscription(distributed)

-

5.8.5 Delete Subscription(distributed)

-

5.8.6 Notification(distributed)

-
-Distributed Temporal Context Information Provision - operations for providing or managing the Temporal Evolution of Entities and Attributes -
-

5.6.11 Upsert Temporal Evolution of an Entity(distributed)

-

5.6.12 Add Attributes to Temporal Evolution of an Entity(distributed)

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity(distributed)

-

5.6.14 Partial Update Attribute instance(distributed)

-

5.6.15 Delete Attribute Instance(distributed)

-

5.6.16 Delete Temporal Evolution of an Entity(distributed)

-
-Distributed Temporal Context Information Consumption - operations for consuming the Temporal Evolution of Entities -
-

5.7.3 Retrieve Temporal Evolution of an Entity(distributed)

-

5.7.4 Query Temporal Evolution of Entities(distributed)

-
-Support operations for distributed operations -
-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMap for Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.15.1 Retrieve Context Source Identity Information

-
-

Registry API

-
-Context Source Registration- operations for registering Context Sourcesand managing Context Source Registrations(CSRs) -
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Context SourceDiscovery - operations for retrieving and discovering CSRs -
-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-
-Context Source RegistrationSubscription - operations for subscribing to CSRs, receiving notifications and managing CSRs -
-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-

5.11.7 CSR Notification

-
-Snapshot API -
-Operations for creating and managing Snapshots. -
-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-
-JSONLDContext API -
-Storing, managing and serving@contexts -
-

5.13.2 Add @context

-

5.13.3 List @contexts

-

5.13.4 Serve @context

-

5.13.5 Delete and Reload @context

-
-

All Context Brokers shall implement the Core API. Context Brokers supporting distributed and federated deployments shall also implement the Distributed 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 Snapshot API and the JSONLDContext API are optional. The managing and serving of @contexts can also be handled by an independent, stand-alone component.

-
-

Table 4.3.5-2: Main implementation configurations

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Description -
-Temporal API -
-RegistryAPI -
-Central Broker without temporal support -
-none -
-none -
-Central Broker with integrated temporal component -
-local -
-none -
-Central Broker with separate temporal component -
-separate -
-none -
-Context Broker supporting distributed and federated deployments without temporal support and with integrated Context Registry -
-none -
-local -
-Context Broker supporting distributed and federated deployments with integrated temporal component and integrated Context Registry -
-local -
-local -
-Context Broker supporting distributed and federated deployments with separate temporal component and integrated Context Registry -
-separate -
-local -
-Context Broker supporting distributed and federated deployments without temporal support and separate Context Registry -
-none -
-separate -
-Context Broker supporting distributed and federated deployments with integrated temporal component and separate Context Registry -
-local -
-separate -
-Context Broker supporting distributed and federated deployments with separate temporal component and separate Context Registry -
-separate -
-separate -
-

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.

-
-

Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-NGSI-LD Role -
-Implements -
-Uses -
-Context Consumer -
-

5.8.6 Notification - if supporting asynchronous interactions

-

In case of direct interactions with Context Registry:

-

5.11.7 CSR Notification -if supporting asynchronous interactions

-
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMapfor Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

-

5.15.1 Retrieve Context Source Identity Information

-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-

In case of direct interactions with Context Registry:

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

if supporting asynchronous interactions:

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-Context Producer -
-none -
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-
-Context Source -
-

5.7.1 Retrieve Entity

-

5.7.2 Query Entities

-

5.7.5 Retrieve Available Entity Types

-

5.7.6 Retrieve Details of Available Entity Types

-

5.7.7 Retrieve Available Entity Type Information

-

5.7.8 Retrieve Available Attributes

-

5.7.9 Retrieve Details of Available Attributes

-

5.7.10 Retrieve Available Attribute Information

-

5.8.1 Create Subscription

-

5.8.2 Update Subscription

-

5.8.3 Retrieve Subscription

-

5.8.4 Query Subscription

-

5.8.5 Delete Subscription

-

5.14.1 Retrieve EntityMap

-

5.14.2 Update EntityMap

-

5.14.3 Delete EntityMap

-

5.14.4 Create EntityMapfor Query Entities

-

5.14.5 Create EntityMap for Query Temporal Evolution of Entities5.15.1 Retrieve Context Source Identity Information

-
-

5.8.6 Notification

-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Context Repository -
-

5.6.1 Create Entity

-

5.6.2 Update Attributes

-

5.6.3 Append Attributes

-

5.6.4 Partial Attribute Update

-

5.6.5 Delete Attribute

-

5.6.6 Delete Entity

-

5.6.7 Batch Entity Creation

-

5.6.8 Batch Entity Upsert

-

5.6.9 Batch Entity Update

-

5.6.10 Batch Entity Delete

-

5.6.17 Merge Entity

-

5.6.18 Replace Entity

-

5.6.19 Replace Attribute

-

5.6.20 Batch Entity Merge

-

5.16.1 Create Snapshot

-

5.16.2 Clone Snapshot

-

5.16.3 Retrieve Snapshot Status

-

5.16.4 Update Snapshot Status

-

5.16.5 Delete Snapshot

-

5.16.6 Snapshot Status Notification

-
-none -
-Temporal Context Consumer -
-

In case of direct interactions with Context Registry:

-

5.11.7 CSR Notification - if supporting asynchronous interactions

-
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-

In case of direct interactions with Context Registry:

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

if supporting asynchronous interactions:

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-Temporal Context Producer -
-None -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-Temporal Context Source -
-

5.7.3 Retrieve Temporal Evolution of an Entity

-

5.7.4 Query Temporal Evolution of Entities

-
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-
-Temporal Context Repository -
-

5.6.11 Upsert Temporal Evolution of an Entity

-

5.6.12 Add Attributes to Temporal Evolution of an Entity

-

5.6.13 Delete Attributes from Temporal Evolution of an Entity

-

5.6.14 Partial Update Attribute instance

-

5.6.15 Delete Attribute Instance

-

5.6.16 Delete Temporal Evolution of an Entity

-
-none -
-Context Registry -
-

5.9.2 Register Context Source

-

5.9.3 Update CSR

-

5.9.4 Delete CSR

-

5.7.1 Retrieve CSR

-

5.7.2 Query CSRs

-

5.11.2 Create CSR Subscription

-

5.11.3 Update CSR Subscription

-

5.11.4 Retrieve CSR Subscription

-

5.11.5 Query CSR Subscription

-

5.11.6 Delete CSR Subscription

-
-5.11.7 CSR Notification -
-

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

-

It is the responsibility of the Context Broker to respect the registration parameters when issuing distributed requests. For instance, if a registration states that only Entities of a given type are offered, the distributed request does not contain additional types. Such a strict requirement is justified because Context Sources (the receivers of the distributed request) are not in a position to determine whether a request has been triggered by a registration, rendering them unable to ensure that the registration parameters are respected in the first place. This applies for any kind of context data a Context Broker can exchange such as Entity IDs, entity types, attribute names, geofenced areas, etc. Ultimately, all constraints specified in the registration shall be respected.

-

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 everyContext 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 relates 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 redirect Context Source Registration also specifies that the registered context data is held in a location external to the Context Broker. It is possible to register (any combination of):

-
-
    -
  • 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 Brokeritself 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 Sourceare 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 [27])) 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

-

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration is present, it contains, whatever extra information the Context Broker shall convey when contacting the Context Source. This can be information the Context Broker needs to successfully communicate with the Context Source (e.g. Authorization material), or for the Context Source to correctly interpret the received content (e.g. the Link URL to fetch an @context). The method for conveying this information is binding-specific, e.g. using headers in the case of HTTP. Instead of providing the actual value, the special value “urn:ngsi-ld:request” can be used to indicate that the respective value is to be taken from the request that triggered the given request, if present.

-
-
-

EXAMPLE:

-
-
-

If the key value pair “user”: “urn:ngsi-ld:request” is part of contextSourceInfo of the CSourceRegistration, the Context Broker checks if “user” was conveyed in the triggering request. If this is the case, e.g. “user”: “abcd” , “user”: “abcd” is also conveyed when contacting the 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

-

The following key-values have a specific well-defined meaning when defined as elements within the optional array contextSourceInfo of the CSourceRegistration.

-

4.3.6.7 Querying and Retrieving 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 process each Context Consumption request efficiently, and to support consistent pagination, it is necessary for the Context Broker to initially make a broad request to each registered Context Source whose registration is matching the request.

-

In the case of a query Entities operation (clause 5.7.2) or query Temporal Evolution of Entities operation (clause 5.7.4), a list of Entity identifiers is returned and stored together with the registration information in an Entity map. Only the Entities whose identifiers are contained in the Entity map are considered when rendering the result pages. Filtering based on queries, geoqueries, scope queries or attribute filters, as provided in the original query request, is applied to the Entities before adding the Entity to a result page, i.e. identifiers of Entities not matching the filters at the time of checking are removed from the Entity map.

-

In the case of a retrieve Entity operation (clause 5.7.1) or retrieve Temporal Evolution of an Entity operation (clause 5.7.3), an Entity map can be used to make subsequent retrievals of the same Entity more efficient, as the Entity map provides the information about which Context Source(s) store relevant Entity information, and other Context Sources do not have to be considered.

-

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 Table 6.4.3.2‑2) 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.

-

When executing Context Consumption or Subscription operations, a significant optimization in performance can be achieved if it is known a priori whether individual Entities are themselves distributed among Context Brokers and Context Sources, or if each Context Broker and Context Source always stores complete Entities. In the latter case all parameters used for filtering such as queries, geoqueries, scope queries or attribute filters can be forwarded and applied locally, whereas in the former case, the Entity first has to be assembled by the Context Broker and only then the filtering can be applied. Since being able to apply filters locally is significantly more efficient, a parameter can indicate that, for the given request, only Entities are to be expected that are stored in their entirety on each Context Broker and each Context Sources, and there are no Entities that are themselves stored in a distributed fashion. Such Entities are also referred to as split Entities. ContextBroker implementations should enable configuring a default for this parameter, so deployments where no split Entities are to be expected can filter locally and thus be more efficient.

-

In the case of split Entities, EntityMaps initially only store “candidate Entities” as no filters could be applied, because only a part of the Entity was available. In the process of pagination, the filters will be (re-)checked. Any Entity not (or no longer) fulfilling the filter shall be removed from the EntityMap.

-

4.3.6.8 Backwards compatibility of Context Source payloads

-

When retrieving Entity data found distributed across multiple associated Context Brokers each Context Source is sent a context consumption request. A Context Broker shall assume that every Context Source will return valid NGSI-LD Entity data in a format that it understands and it shall reject data that is invalid. However, since the definition of a valid NGSI-LD Entity has broadened with each version of the NGSI-LD specification, it is possible that a registered Context Sourcecould respond with valid NGSI-LD Entity data which does not fit the narrower confines of a previous NGSI-LD specification.

-

Therefore when making a context consumption request, a Context Broker may wish to indicate that it is only capable of interpreting responses which conform to a specific NGSI-LD specification, in which case the Context Sourceshall endeavour to amend its payload accordingly. Table 4.3.6.7‑1 describes a minimal level of support for a NGSI-LD Entity data as specified by each version of the NGSI-LD specification, and the expected fallback behaviour required if a context consumption request is made to receive data conformant to an earlier version of the NGSI-LD specification. Table 4.3.6.7‑2 describes conformance fallbacks for an NGSI-LD Property (and its subclasses) and Table 4.3.6.7‑2 describes conformance fallbacks for an NGSI-LD Relationship (and its subclasses).

-

The version of the NGSI-LD specification requested and the conformant version returned is defined in the form major.minor, for example 1.5.

-
-

Table 4.3.6.8-1: NGSI-LD Entity data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-

Version

-

Introduced

-
-Conformant Data Fallback -
-id -
-String -
-Valid URI -
-1.0 -
-
-type -
-String or String[] (see note 1) -
-1.0 -
-
-
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove attribute from payload -
-location -
-GeoProperty -
-Default geospatial Property of an entity. See clause 4.7 -
-1.0 -
-
-observationSpace -
-GeoProperty -
-See clause 4.7 -
-1.0 -
-
-operationSpace -
-GeoProperty -
-See clause 4.7 -
-1.0 -
-
-scope -
-String or String[] -
-See clause 4.18 -
-1.4 -
-Remove attribute from payload -
-<Property name> -
-Property or Property[] (see note 2) -
-Property as mandated by clause 4.5.2. -
-1.0 -
-
-GeoProperty or GeoProperty[] (see note 2) -
-GeoProperty as mandated by clause 4.5.2. -
-1.0 -
-
-LanguageProperty or LanguageProperty[] (see note 2) -
-LanguageProperty as mandated by clause 4.5.18. -
-1.4 -
-Reformat attribute as Property -
-JsonProperty or JsonProperty[] (see note 2) -
-JsonProperty as mandated by clause 4.5.24. -
-1.8 -
-Reformat attribute as Property -
-VocabProperty or VocabProperty[] (see note 2) -
-VocabProperty as mandated by clause 4.5.20. -
-1.8 -
-Reformat attribute as Property -
-ListProperty or ListProperty[] (see note 1) -
-ListProperty as mandated by clause 4.5.21. -
-1.8 -
-Reformat attribute as Property -
-<Relationship name> -
-

Relationship

-

or Relationship[] (see note 3)

-
-Relationship as mandated by clause 4.5.3. -
-1.0 -
-
-ListRelationship or ListRelationship[] (see note 3) -
-ListRelationship as mandated by clause 4.5.22. -
-1.8 -
-Reformat attribute as Relationship -
-
-
-

NOTE 1:

-
-
-

From 1.3 onwards, an Entity type can be assigned multiple values For 1.0 backwards compatibility only return a single element with preference to the first instance.

-
-
-
-
-

NOTE 2:

-
-
-

From 1.3 onwards, multiple instances of a Property (or subclass of Property ) identified by the same Property name can be separated by datasetId. For 1.0 backwards compatibility only return a single element of Property Array with preference to the default instance.

-
-
-
-
-

NOTE 3:

-
-
-

From 1.3 onwards, multiple instances of a Relationship (or subclass of Relationship ) identified by the same Relationship name can be separated by datasetId. From 1.3 onwards. For 1.0 backwards compatibility only return a single element of Relationship Array with preference to the default instance.

-
-
-
-
-

Table 4.3.6.8-2: NGSI-LD Property data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-Version Introduced -
-Conformant Data Fallback -
-type -
-String -
-1.0 -
-
-
-value -
-Any JSON value as defined by IETF RFC 8259 [6] -
-See NGSI-LD Value definition in clause 3.1 -
-1.0 -
-
-datasetId -
-String -
-Valid URI as mandated by clause 4.5.5 -
-1.3 -
-Remove attribute from payload -
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove atrribute from payload -
-observedAt -
-String -
-DateTime as mandated by clause 4.8 -
-1.3 -
-Remove attribute from payload -
-unitCode -
-String -
-As mandated by [15] -
-1.3 -
-Remove attribute from payload -
-valueType -
-String -
-See clause 4.5.2 -
-1.9 -
-Remove attribute from payload -
-
-

Table 4.3.6.8-3: NGSI-LD Relationship data type attribute support

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Name -
-Data Type -
-Definition -
-Version Introduced -
-Conformant Data Fallback -
-type -
-String -
-Valid URI -
-1.0 -
-
-object -
-String or String[] -
-1.0 -
-
-
-datasetId -
-String -
-Valid URI as mandated by clause 4.5.5 -
-1.3 -
-Remove attribute from payload -
-expiresAt -
-String -
-DateTime as mandated by clause 4.22 -
-1.9 -
-Remove attribute from payload -
-objectType -
-String or String[] -
-See clause 4.5.23 -
-1.8 -
-Remove attribute from payload -
-observedAt -
-String -
-DateTime as mandated by clause 4.8 -
-1.3 -
-Remove attribute from payload -
-

When responding to a context consumption request to supply data conforming to a specific NGSI-LD specification, Context Sources should indicate the version of the specification the returned payload actually conforms to. In general, Context Sources will not be expected to be flexibile enough to supply payloads conformant to all past and future versions of the specification, but the requesting Context Broker may use supplied version information when collating data from multiple Context Sources. and to validate and amend received payloads.

-

4.3.7 Snapshots

-

Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables “freezing” the result by retrieving all results immediately and persisting them locally. Context Consumers can then query and analyse the Snapshot in a much more consistent way.

-

This is especially relevant for distributed cases, where information initially was distributed across multiple Context Brokers and Context Sources.

-

Snapshots offer the full functionality of NGSI-LD available locally and can be used as a basis for simulations that enable making predictions or “what-if” analyses, which are often needed for digital twins.

-

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.9.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>.
    • -
-
-

Whereas the Core NGSI-LD @context contains JSON-LD Scoped Contexts, the user @context shall not contain JSON-LD Scoped Contexts (see [2], section 4.1.8), as described in clause 5.5.7, because this would enable overwriting terms defined in the Core NGSI-LD @context.

-

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. If an array is required, an array with one single NGSI-LD Null is used. 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

-
-
    -
  • “expiresAt”: a string as mandated by clause 4.22.
    • -
  • “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.
    • -
-
-
-
-

NOTE 1:

-
-
-

In the following, the term Attribute is used when referring in the text to both a Property and a Relationship (see definition of NGSI-LD Attribute in clause 3.1 ).

-
-
-
-
-

NOTE 2:

-
-
-

When GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.16 for details.

-
-
-

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). The datatype URI can be placed in the optional “valueType” member.

    -
    -
    -

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

    -
    • -
-

It should be noted that in the JSON-LD serialization, a number data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker’s internal representation, a number is equivalent to either an integer or floating point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process.

-

Optional

-
-
    -
  • “datasetId”: a URI as mandated by clause 4.5.5.
    • -
  • “expiresAt”: a string as mandated by clause 4.22.
    • -
  • “ngsildproof”: a Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C®Data integrity “proof” structure [35]. See annex C.11 for an example.
    • -
  • “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].
    • -
  • “valueType”: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD @type for the Property value. When it is a JSON primitive, it should align this with the RDF datatype [34].
    • -
  • 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.
    • -
  • “entityIdSealed”and“entityTypeSealed”shall never be present, unless the Property name is “ngsildproof”.
    • -
  • “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). If the provided value is a JSON object and contains a “type” field, the whole Attribute shall be treated as a normalized representation (see clause 4.5.2.2).

-

An NGSI-LD Property which includes 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) which includes the following members:

-

Mandatory

-
    -
  • -

    “value”: the Property Value (see definition of NGSI-LD Value in clause 3.1). The datatype URI can be placed in the optional “valueType” member. 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).

    -
    -
    -

    It should be noted that in the JSON-LD serialization, a number data type does not allow for leading zeros, and octal and hexadecimal formats are not used. In the context broker’s internal representation, a number is equivalent to either an integer or floating point number, depending on if the number has a non-zero fractional part. The degree of precision of a floating point number held within a context broker will depend upon the implementation, and insignificant digits may be lost during the deserialization and serialization process.

    -
    • -
-

Optional

-
-
    -
  • “datasetId”: a URI as mandated by clause 4.5.5.
    • -
  • “expiresAt”: a string as mandated by clause 4.22.
    • -
  • “ngsildproof”: a Property with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C®Data integrity “proof” structure [35]. See annex C.11 for an example.
    • -
  • “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].
    • -
  • “valueType”: a string value which shall be type coerced into a datatype URI. It is a non-reified alternative to the use of a native JSON-LD @type for the Property value. When it is a JSON primitive, it should align this with the RDF datatype [34].
    • -
  • 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.
    • -
  • “entityIdSealed”and“entityTypeSealed”shall never be present, unless the Property name is “ngsildproof”.
    • -
  • “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.
    • -
  • “expiresAt”: a string as mandated by clause 4.22.
    • -
  • “ngsildproof”: a Property, as mandated by clause 4.5.2, with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C®Data integrity “proof” structure [35]. See annex C.11 for an example.
    • -
  • “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

-
-
    -
  • “entityIdSealed”and“entityTypeSealed”shall never be present.
    • -
  • “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.
    • -
  • “expiresAt”: a string as mandated by clause 4.22.
    • -
  • “ngsildproof”: a Property, as mandated by clause 4.5.2, with the non-reified subproperties “entityIdSealed” and “entityTypeSealed”as specified in [35]. The value of its “value” element shall be an object containing the W3C®Data integrity “proof” structure [35]. See annex C.11 for an example.
    • -
  • “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

-
-
    -
  • “entityIdSealed”and“entityTypeSealed”shall never be present.
    • -
  • “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.
    • -
-
-
-
-

EXAMPLE 1:

-
-
-

“name”: “David Robert Jones”

-
-
-
-
    -
  • 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 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”.
    • -
-
-
-
-

EXAMPLE 2:

-
-
-
"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:

-
-
-
"devices": [
-     "urn:ngsi-ld:Device:14142",
-     "urn:ngsi-ld:Device:13562", 
-     "urn:ngsi-ld:Device:37309"
-]
-
-
-
-
    -
  • 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:

-
-
-
"providedBy": {
-  "id": "urn:ngsi-ld:Device:31415",
-  "type": "Device",
-  "brandName": "Anemometer",
-  "manufacturerName": "Cyberdyne Systems",
-  "windSpeed": 60
-}
-
-
-
-
-

EXAMPLE 10:

-
-
-
"devices": [
-    {
-       "id": "urn:ngsi-ld:Device:14142",
-       "type": "Device",
-       "brandName": "Anemometer",
-       "manufacturerName": "Cyberdyne Systems",
-        "windSpeed": 60
-    },
-    {
-       "id": "urn:ngsi-ld:Device:13562",
-       "type": "Device",
-       "brandName": "Hygromometer",
-       "manufacturerName": "Acme Corporation",
-       "humidity": 64
-    },
-    { 
-       "id": "urn:ngsi-ld:Device:37309",
-       "type": "Device",
-       "brandName": "Barometer",
-       "manufacturerName": "Trask Industries",
-       "pressure": 760
-    }
-]
-
-
-
-
    -
  • 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:

-
-
-
[
-  {
-    …etc
-    "providedBy": "urn:ngsi-ld:Device:31415"
-  },
-  {
-    "id": "urn:ngsi-ld:Device:31415",
-    "type": "Device",
-    "brandName": "Anemometer",
-    "manufacturerName": "Cyberdyne Systems",
-    "windSpeed": 60
-  }
-]
-
-
-
-
-

EXAMPLE 12:

-
-
-
[
-    {
-      … etc
-      "providedBy": [
-       "urn:ngsi-ld:Device:14142", 
-         "urn:ngsi-ld:Device:13562", 
-         "urn:ngsi-ld:Device:37309"
-       ]
-    },
-    {
-       "id": "urn:ngsi-ld:Device:14142",
-       "type": "Device",
-       "brandName": "Anemometer",
-       "manufacturerName": "Cyberdyne Systems",
-       "windSpeed": 60
-    },
-    {
-       "id": "urn:ngsi-ld:Device:13562",
-       "type": "Device",
-       "brandName": "Hygromometer",
-       "manufacturerName": "Acme Corporation",
-       "humidity": 64
-    },
-    {
-       "id": "urn:ngsi-ld:Device:37309",
-       "type": "Device",
-       "brandName": "Barometer",
-       "manufacturerName": "Trask Industries",
-       "pressure": 760
-    }
-]
-
-
-
-
    -
  • 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 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.
    • -
-
-
-
-

EXAMPLE 14:

-
-
-

“periods”: [“First”, “Second”, “Third”, “Fourth”]

-
-
-
    -
  • 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 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).
    • -
-
-
-
-

EXAMPLE 16:

-
-
-
"route":[
-  "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.
    • -
-
-
-
-

EXAMPLE 17:

-
-
-
"route": [
-  {
-    "id": "urn:ngsi-ld: BusStop:0101",
-    "type": "BusStop",
-    "stopName": "High Street",
-    "location": {"type": Point, coordinates [54.112,0.334]}}
-  },
-  {
-    "id": "urn:ngsi-ld: BusStop:0102",
-    "type": "BusStop",
-    "stopName": "Station Road", 
-    "location": {"type": Point, coordinates [54.101,0.302]}}
-  },
-  {
-    "id": "urn:ngsi-ld: BusStop:9912",
-    "type": "BusStop",
-    "stopName": "Mornington Cresent", 
-    "location": {"type": Point, coordinates [54.142,0.332]}
-  }
-]
-
-
-
-
    -
  • 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.
    • -
-
-
-
-

EXAMPLE 18:

-
-
-
[
-  {
-    …etc
-    "route": [
-      "urn:ngsi-ld:BusStop:0101",
-      "urn:ngsi-ld:BusStop:0102",
-      "urn:ngsi-ld:BusStop:9912"
-    ]
-  },
-  {
-    "id": "urn:ngsi-ld: BusStop:0101"
-    "type": "BusStop",
-    "stopName": "High Street", 
-    "location: {"type": "Point", "coordinates": [54.112,0.334]}}
-  {
-    "id": "urn:ngsi-ld: BusStop:0102",
-    "type": "BusStop",
-    "stopName": "Station Road", 
-    "location": {"type": "Point", "coordinates": [54.101,0.302]}}
-  },
-  {
-    "id": "urn:ngsi-ld:BusStop:9912"
-    "type": "BusStop",
-    "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 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"
-    ]
-  }
-}
-
-
-
-
-

NOTE:

-
-
-

When the simplified GeoJSON representation is selected, the layout of the Entities changes, see clause 4.5.17 for details.

-
-
-

4.5.5 Multi-Attribute Support

-

4.5.5.1 Introduction

-

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 datasetIdcan 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, expiresAt and observedAt, and also the unitCode Property.

-

4.5.5.2 Processing of Conflicting Transient Entities

-

In case of conflicting information when an Entity is received from a registered Context Sourceand marked with an expiresAt DateTime, but this expiresAt is not duplicated across all versions of the Entity received across all registered Context Sources, the following mechanism shall be used to differenciate:

-

For each version of the Entity received where the expiresAt non-reified attribute is present at the Entity level:

-
    -

  • If no expiresAt attribute is present as a property of an Attribute, a non-reified expiresAt attribute is added as a property of that Attribute corresponding to to the expiresAt found on the Entity.

    • -

  • If the expiresAt attribute is present as a property of an Attribute, and the value on the Attribute is further in the future than the expiresAt value found on the Entity, the value of the expiresAt on the Attribute is overwritten to corresponding to the earlier DateTime.

    • -
-

4.5.5.3 Processing of Conflicting Attributes

-

In case of conflicting information for an Attribute, where a datasetId is duplicated, but there are differences in the other attribute data, if an expiresAt DateTime is present on the Attribute and the date lies in the past, it shall be discarded, thereafter 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.

-

When conflicting information is received for the non-reified expiresAt attribute at an Entity level:

-
    -

  • If an expiresAt attribute is missing from at least one version of the Entity received from registered Context Sources, the expiresAt attribute is removed from the Entity.

    • -

  • Otherwise the expiresAt attribute of the Entity is set to the DateTime corresponding to the expiresAt DateTime which is furthest in the future.

    • -
-

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 (or a single JSON-LD object in case only one is present), 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 a 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 (or a single JSON-LD object in case only one is present), 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"
-    ]
-  ]
-}
-
-
-
-
-

EXAMPLE 7:

-
-
-
"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 8:

-
-
-
"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:

-
-

Prohibited

-
-
-
    -
  • “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:

-

Prohibited

-
-
    -
  • “unitCode”: shall never be present, as language maps are always strings and hence unitless.
    • -
  • “value” and “previousValue”: 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:
    • -
-
-
-
    -
  1. the value obtained after applying the aggregation method over the period;
    2. -
-
-
-
    -
  1. the start DateTime of the corresponding period;
    2. -
-
-
-
    -
  1. the end DateTime of the corresponding period.
    2. -
-
-
-
    -
  • 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:
    • -
-
-
-
    -
  1. the value obtained after applying the aggregation method over the period;
    2. -
-
-
-
    -
  1. the start DateTime of the corresponding period;
    2. -
-
-
-
    -
  1. the end DateTime of the corresponding period.
    2. -
-
-

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 = “avg” / “distinctCount” / “max” / “min” / “stddev” / “sum” / “sumsq” / “totalCount”
    • -
-
-

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

-
-

Table 4.5.19.1-1: Semantics of aggregation methods for Properties on JSON native data types

-
- -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Aggregation Method -
-JSON String -
-JSON Number -
-JSON Object -
-JSON Array -
-

JSON Boolean

-

(see note)

-
-avg -
-N/A -
-Calculate the average of the values inside the period -
-N/A -
-Calculate the average number of the sizes of the arrays inside the period -
-Calculate the average of the values inside the period -
-distinctCount -
-Calculate the count of distinct values inside the period -
-max -
-Calculate the last value in lexicographical order inside the period -
-Calculate the maximum value inside the period -
-N/A -
-Calculate the maximum size of the arrays inside the period -
-Calculate the maximum value inside the period -
-min -
-Calculate the first value in lexicographical order inside the period -
-Calculate the minimum value inside the period -
-N/A -
-Calculate the minimum size of the arrays inside the period -
-Calculate the minimum value inside the period -
-stddev -
-N/A -
-Calculate the standard deviation of the values inside the period -
-N/A -
-N/A -
-Calculate the standard deviation of the values inside the period -
-sum -
-N/A -
-Calculate the sum of the values inside the period -
-N/A -
-Calculate the sum of the sizes of the arrays inside the period -
-Calculate the sum of the values inside the period -
-sumsq -
-N/A -
-Calculate the sum of the square of the values inside the period -
-N/A -
-N/A -
-Calculate the sum of the square of the values inside the period -
-totalCount -
-Calculate the number of times the value has been updated inside the period -
-
-
-

NOTE:

-
-
-

For the purpose of aggregation, true is considered as a value of 1, false is considered as a value of 0.

-
-
-
-
-

Table 4.5.19.1-2: Semantics of aggregation methods for Properties on other supported data types

-
- ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Aggregation Method

-
-

DateTime

-
-

Date

-
-

Time

-
-

URI

-
-avg -
-N/A -
-N/A -
-Calculate the average time inside the period (e.g. to apply on an event that occurs at non fixed times, like the time a car enters a given parking) -
-N/A -
-distinctCount -
-Calculate the count of distinct values inside the period -
-max -
-Calculate the maximum value inside the period -
-Calculate the maximum value inside the period -
-Calculate the maximum value inside the period -
-N/A -
-min -
-Calculate the minimum value inside the period -
-Calculate the minimum value inside the period -
-Calculate the minimum value inside the period -
-N/A -
-stddev -
-N/A -
-N/A -
-N/A -
-N/A -
-sum -
-N/A -
-N/A -
-N/A -
-N/A -
-sumsq -
-N/A -
-N/A -
-N/A -
-N/A -
-totalCount -
-Calculate the number of times the value has been updated inside the period -
-
-

Table 4.5.19.1-3: Semantics of aggregation methods for Relationships

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Aggregation Method

-
-

Relationship

-
-avg -
-

N/A

-
-distinctCount -
-

Calculate the count of distinct relationships targets inside the period

-
-max -
-

N/A

-
-min -
-

N/A

-
-stddev -
-

N/A

-
-sum -
-

N/A

-
-sumsq -
-

N/A

-
-totalCount -
-

Calculate the number of times the relationship has been updated inside the period

-
-

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:

-

Prohibited

-
-
    -
  • “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:

-

Prohibited

-
-
    -
  • “unitCode”: shall never be present, as vocabs are always strings and hence unitless.
    • -
  • “value” and “previousValue”: 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 clause 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:

-

Prohibited

-
-
    -
  • “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 clause 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:

-
-

Prohibited

-
-
-
    -
  • “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:

-

Prohibited

-
-
    -
  • “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:

-

Prohibited

-
-
    -
  • “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.

-

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

-

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:

-

Prohibited

-
-
    -
  • “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:

-

Prohibited

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

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:

-
nameChar = unicodeNumber / unicodeLetter
-nameChar =/ %x5F                  ; _
-name = unicodeLetter *nameChar
-
-
    -
  • 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:

-
prefix = unicodeLetter *nameChar
-name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name
-

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

NOTE 1:

-
-
-

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used .

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

NOTE 2:

-
-
-

In previous versions of NGSI-LD, only the comma was supported as ISO 8601 [17] states that it is the preferred option. However, in practice the decimal point is more commonly used.

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

-

GeoJSON coordinates shall be considered as consisting of values of a JSON-LD floating point number data type. The degree of precision of a latitude and longitude (and optional altitude) held within a context broker will depend upon the implementation. Implementors should note that the GeoJSON specification itself recommends 6 decimal places for latitude and longitude which equates to roughly 10cm of precision.

-

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.
    • -
  • expiresAt is defined as the temporal Property at which the Entity, Property, Relationship, CSourceRegistration, Subscription or Snapshot should be deleted from an NGSI-LD system.
    • -
  • lastUsedAt is defined as the temporal Property at which a Snapshot has been most recently used, i.e. when the most recent operation has been executed on this Snapshot.
    • -
-
-

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

-
-
-

NOTE 1:

-
-
-

For simplicity reasons, a TemporalProperty is represented only by its Value, i.e. no Properties of TemporalProperty nor Relationships of TemporalProperty can be conveyed. In more formal language, a TemporalProperty does not allow reification.

-
-
-
-
-

NOTE 2:

-
-
-

It is important to remark that the term TemporalProperty has been reserved for the semantic tagging of non-reified structural timestamps ( observedAt , createdAt , modifiedAt, deletedAt , expiresAt ), which capture the temporal evolution of Attributes. Only such structural timestamps can be used as timeproperty in Temporal Queries as mandated by clause 4.11 .

-
-
-
-
-

NOTE 3:

-
-
-

User-defined Properties whose value is a time value ( Date, DateTime or Time ) are defined as Property , not as TemporalProperty , and are serialized in NGSI-LD as shown in annex C, clause C.6 .

-
-
-

Whenever a TemporalProperty value is unknown by a registered Context Source, the Property shall be omitted rather than sending an error response.

-

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).
    • -
  • filter out Snapshots by the values of the Snapshot data type members, i.e. when filtering Snapshots, only the names of the members defined for Snapshot in Table 5.2.43‑1 are allowed values for AttrName.
    • -
-
-

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://github.com/ietf-tools/bap>), and it shall be supported by implementations:

-
Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm /
-QueryTermAssoc))
-QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ;
-(QueryTerm)
-QueryTerm = Attribute
-QueryTerm =/ Attribute Operator ComparableValue
-QueryTerm =/ Attribute equal CompEqualityValue
-QueryTerm =/ Attribute unequal CompEqualityValue
-QueryTerm =/ Attribute patternOp RegExp
-QueryTerm =/ Attribute notPatternOp RegExp
-Attribute = LinkedEntityRelation
-LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D          ;
-AttrName{LinkedEntityPath}
-LinkedEntityRelation =/ ValuePath
-LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B
-LinkedEntityPath %x7D
-;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath}
-LinkedEntityPath =/ ValuePath
-ValuePath = DottedPath *1(%x5B DottedPath %x5D)                     ; DottedPath
-*1([DottedPath])
-DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName)
-Operator = equal / unequal / greaterEq / greater / lessEq / less
-ComparableValue = Number / quotedStr / dateTime / date / time
-OtherValue = false / true
-Value = ComparableValue / OtherValue
-Range = ComparableValue dots ComparableValue
-ValueList = Value 1*(%x2C Value) ; Value 1*(, Value)
-CompEqualityValue = OtherValue / ValueList / Range / URI
-equal = %x3D %x3D ; ==
-unequal = %x21 %x3D ; !=
-greater = %x3E ; >
-greaterEq = %x3E %x3D ; >=
-less = %x3C ; <
-lessEq = %x3C %x3D ; <=
-patternOp = %x7E %x3D ; ~=
-notPatternOp = %x21 %x7E %x3D ; !~=
-dots = %x2E %x2E ; ..
-TermChar = unicodeNumber / unicodeLetter
-TermChar =/ %x5F ; _
-AttrName = unicodeLetter *TermChar
-EntityType = unicodeLetter *TermChar
-quotedStr = String ; "*char"
-andOp = %x3B ; ;
-orOp = %x7C ; |
-LogicalOp = andOp / orOp
-
-
    -
  • 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.

-
-
-

EXAMPLE 0:

-
-
-

?q=temperature . (checks for the existence of the attribute temperature)

-
-
-
-
-

EXAMPLE 1:

-
-
-

?q=temperature==20

-
-
-
-
-

EXAMPLE 2:

-
-
-

?q=brandName!=“Mercedes”

-
-
-
-
-

EXAMPLE 3:

-
-
-

?q=isParked==“urn:ngsi-ld:OffStreetParking:Downtown1”

-
-
-
-
-

EXAMPLE 4:

-
-
-

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 . The NGSI-LD query language string is conveyed by means of parameter q.

-
-
-
-
-

EXAMPLE 5:

-
-
-

?q=isMonitoredBy (to query Entities that have the Attribute isMonitoredBy )

-
-
-

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.

-
-
-

EXAMPLE 6:

-
-
-

?q=((speed>50|rpm>3000);brandName==“Mercedes”)

-
-
-
-
-

EXAMPLE 7:

-
-
-

?q=(temperature>=20;temperature<=25)|capacity<=10

-
-
-

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

EXAMPLE 8:

-
-
-

?q=temperature.observedAt>=2017-12-24T12:00:00Z

-
-
-

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.

-
-
-

EXAMPLE 9:

-
-
-

?q=address[city]==“Berlin” . The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property , which is a complex JSON object representing a postal address. Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:placedescription:123",
-  "type": "PlaceDescription",
-  "address": {
-    "type": "Property",
-    "value": {
-      "city": "Berlin",
-      "street": "Ulrich Strasse"
-    }
-  }
-}
-
-
-
-
-

EXAMPLE 10:

-
-
-

?q=sensor.rawdata[airquality.particulate]==40 . The trailing path is [airquality.particulate]. The particulate Property of the compound JSON object is targeted. Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:particulatemeasurement:345",
-  "type": "ParticulateMeasurement",
-  "sensor": {
-    "type": "Property",
-    "value": 40,
-    "rawdata": {
-      "type": "Property",
-      "value": {
-        "airquality": {
-          "particulate": 40,
-          "PM20": 85
-        }
-      }
-    }
-  }
-}
-
-
-
-
-

EXAMPLE 11:

-
-
-

?q=parkingTickets[value]==“Overstay 60 minutes”&jsonKeys=parkingTickets . The trailing path is parkingTickets . The parkingTickets Property of the JSON object is targeted, but the target value raw is JSON, and is not expanded to ngsi-ld:hasValue using the core @context . Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:Car:6152s",
-  "type": "Car",
-  "parkingTickets": {
-  "type": "JsonProperty",
-  "json": {
-         "id": "85a6cc52-0589-45f9",
-         "value": "Overstay 60 minutes"
-      }
-  }
-}
-
-
-
-
-

EXAMPLE 12:

-
-
-

?q=gender==Male&expandValues=gender . The trailing path is gender . The gender Property of JSON object is targeted, but the target value is first expanded to a URI using the supplied @context . Refer to the following NGSI-LD Entity:

-
{
-  "id": "urn:ngsi-ld:Person:678",
-  "type": "Person",
-  "gender": {
-    "type": "VocabProperty",
-    "vocab": "Male",
-    }
-  },
-  @context": {
-    "Male": "http://example.org/Male",
-  }
-}
-
-
-

The filter can also apply to a Property or Relationship of an NGSI-LD Entity targeted by a (recursively) followed Relationship, for example as part of a linked entity retrieval (clause 4.5.23).

-
-
-

EXAMPLE 13:

-
-
-

?q=sensor{humidity}==40 . The trailing path is sensor{humidity} . The query targets entities with a sensor Relationship and makes a sub-query on matching target objects which have the matching humidity Attribute. Refer to the following NGSI-LD Entities:

-
{
-  "id": "urn:ngsi-ld:WeatherStation:123",
-  "type": "WeatherStation",
-  "sensor": {
-    "type": "Relationship",
-     "objectType": "Device",
-    "object": "urn:ngsi-ld:Device:345"
-  }
-}
-{
-  "id": "urn:ngsi-ld:Device:345",
-  "type": "Device",
-  "humidity": {
-    "type": "Property",
-    "value": 40
-  }
-}
-
-
-

As not knowing the Entity Type targeted by a Relationship could make the query significantly more expensive, a hint for the required Entity Type can be provided, so only such NGSI-LD Entities need to be considered.

-
-
-

EXAMPLE 14:

-
-
-

?q=sensor{Device:humidity}==40 . The trailing path is sensor{Device:humidity} . The query targets entities with a sensor.entityType = “Device” within a Relationship and then makes a sub-query on matching target objects which have the matching humidity Attribute. The entityType hint results in a faster lookup. Refer to the following NGSI-LD Entities.

-
{
-  "id": "urn:ngsi-ld:WeatherStation:123",
-  "type": "WeatherStation",
-  "sensor": {
-    "type": "Relationship",
-  "objectType": "Device",
-    "object": "urn:ngsi-ld:Device:345"
-  }
-}
-{
-  "id": "urn:ngsi-ld:Device:345",
-  "type": "Device",
-  "humidity": {
-    "type": "Property",
-    "value": 40
-  }
-}
-
-
-

If the target element corresponds to a Relationship or ListRelationship, the combination of such target element with any operator different than equal or unequal shall result in not matching.

-

A Query Term value shall be any of the following (depending on the operator used):

-
-
    -
  • A literal value (string, number, date, etc.) (production rule named Value).
    • -
  • A range of values (production rule named Range), specified as a minimum and a maximum value.
    • -
  • A regular expression (production rule named RegExp).
    • -
  • A URI (production rule named URI).
    • -
  • A comma-separated list of literal values (production rule named ValueList).
    • -
-
-

When comparing dates or times, the order relation considered shall be a temporal one.

-

When it comes to comparing text strings, implementations:

-
-
    -
  • shall follow the recommendations defined by IETF RFC 8259 [6], section 8.3.
    • -
  • should support the Unicode Collation Algorithm (UCA), as defined by [13].
    • -
-
-

URI comparison should be performed so that the number of false negatives is minimized, as recommended by IETF RFC 3986 [5], section 6.

-

The semantics of the different logical operators used by Query Terms are described as follows and shall be supported by compliant implementations:

-
-
    -
  • Existence (only attribute is specified). A matching entity shall contain the target element.
    • -
  • Equal operator (production rule named equal). A matching Entity shall contain the target element and meet any of the following conditions:
    • -
-
-
-
    -
  • The Query Term value, e.g. color==“red”:
    • -
-
-
-
    -
  • Is identical or equivalent to the target value (e.g. matches “red”).
    • -
  • Is included in the target value, if the latter is an array (e.g. matches [“blue”,“red”,“green”]).
    • -
-
-
-
    -
  • If the Query Term value is a list of values (production rule named ValueList), e.g. color==“black”, “red”:
    • -
-
-
-
    -
  • The target value is identical or equivalent to any of the list values (e.g. matches “red”).
    • -
  • The target value includes any of the Query Term values, if the target value is an array (e.g. matches [“red”,“blue”]).
    • -
-
-
-
    -
  • If the Query Term value is a range (production rule named Range), e.g. temperature==10..20:
    • -
-
-
-
    -
  • The target value is in the interval between the minimum and maximum of the range (both included) (e.g. matches 15).
    • -
-
-
-
    -
  • The Query Term value target element corresponds to a LanguageProperty and a natural language is specified e.g. color[en]==“red”:
    • -
-
-
-
    -
  • a match is found as the value of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: “rouge”, “en”: “red”,“de”: “rot”} but not {“fr”: “red”, “en”: “black”,“de”: “blue”}).
    • -
  • a match is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“red”, “cat],”de”: [“rote”, “Katze”]} but not {“fr”: [“chat”, “rouge”], “en” : [“coal”, “black”],“de”: [“blaue”, “Engel”]}).
    • -
-
-
-
    -
  • The Query Term value target element corresponds to a LanguageProperty and no natural language is specified e.g. color[*]==“red”:
    • -
-
-
-
    -
  • any match is found in the values of the key-value pairs of the languageMap (e.g. matches {“fr”: “rouge”, “en”: “red”, “de”: “rote”}.
    • -
  • a match is found as a single element of the array of values of the key-value pairs of the languageMap (e.g. matches {“fr”: “chat”, “rouge”], “en”: [“red”, “cat”], “de”: [“rote”, “Katze”]}).
    • -
-
-
-
    -
  • The Query Term value is a URI and the target element corresponds to a Relationship,aListRelationshipor aVocabProperty, e.g. color==“http://example/red”:
    • -
-
-
-
    -
  • Is identical to the target value (e.g. matches “http://example.com/red”).
    • -
  • Is included in the target value, if the latter is an array (e.g. matches [“http://example.com/blue”,” http://example.com/red”,” http://example.com/green”]).
    • -
-
-
-
    -
  • If the Query Term value target element corresponds to a Relationship,aListRelationshipor a VocabProperty and is a list of URIs (production rule named ValueList), e.g. color==” http://example/black”,“http://example/red”:
    • -
-
-
-
    -
  • The target value is identical to any of the list values (e.g. matches “http://example.com/red”).
    • -
  • The target value includes any of the Query Term values, if the target value is an array (e.g. matches [“http://example.com/red”, “http://example.com/blue”]).
    • -
-
-
-
    -
  • If there is no equality between the target value data type and the Query Term value data type, then it shall be considered as not matching.
    • -
-
-
-
    -
  • Unequal operator (production rule named unequal). A matching entity shall contain the target element and meet any of the following conditions:
    • -
-
-
-
    -
  • The Query Term value, e.g. color!=“red”:
    • -
-
-
-
    -
  • Is neither identical nor equivalent to the target value (e.g. matches “black”).
    • -
  • Is not included in the target value, if the latter is an array (e.g. matches [“blue”,“black”,“green”], but not [“blue”,“red”,“green”]).
    • -
-
-
-
    -
  • If the Query Term value is a list of values (production rule named ValueList), e.g. color!= “black”, “red”:
    • -
-
-
-
    -
  • The target value is neither identical nor equivalent to any of the list values (e.g. matches “blue”).
    • -
  • The target value does not include any of the list values, if the target value is an array (e.g. matches [“blue”,“yellow”,“green”], but not [“blue”,“red”,“green”]).
    • -
-
-
-
    -
  • If the Query Term value is a range (production rule named Range), e.g. temperature!=10..20:
    • -
-
-
-
    -
  • The target value is not in the interval between the minimum and the maximum (both included) (e.g. matches 9).
    • -
-
-
-
    -
  • The Query Term value target element corresponds to a LanguageProperty and a natural language is specified e.g. color[en]!=“red”:
    • -
-
-
-
    -
  • No matching value is found as the value of the specified language key of a languageMap where a language filter is specified. (e.g. matches {“fr”: “noir”, “en”: “black”,“de”: “schwarz”} but not {“fr”: “rouge”, “en” : “red”,“de”: “rot”}).
    • -
  • No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“coal”, “black”], “de”: [“blaue”, “Engel”]} but not {“fr”: [“rouge”, “noir”], “en” : [“red”, “black”],“de”: [“rot”, “schwarz”]}).
    • -
-
-
-
    -
  • The Query Term value target element corresponds to a LanguageProperty and no language filter is specified e.g. color[*]!=“red”:
    • -
-
-
-
    -
  • No matching value is found in any of the values of the key-value pairs of a languageMap (e.g. matches {“fr”: “noir”, “en”: “black”,“de”: “schwarz”}, but not {“fr”: “rouge”, “en”: “red”,“de”: “rot”}).
    • -
  • No matching value is found as a single element from the array of values of the key-value pair corresponding to the specified natural language of the languageMap (e.g. matches {“fr”: [“chat”, “rouge”], “en”: [“coal”, “black”], “de”: [“blaue”, “Engel”]} but not {“fr”: [“rouge”, “noir”], “en”: [“red”, “black”],“de”: [“rot”, “schwartz”]}).
    • -
-
-
-
    -
  • The Query Term value is a URI and the target element corresponds to a Relationship,aListRelationshipora VocabProperty, e.g. color!=“http://example.com/red”:
    • -
-
-
-
    -
  • Is not identical to the target value (e.g. matches “http://example.com/black”).
    • -
  • Is not included in the target value, if the latter is an array (e.g. matches [“http://example.com/blue”, “http://example.com/black”, “http://example.com/green”], but not [“http://example.com/blue”, “http://example.com/red”, “http://example.com/green”]).
    • -
-
-
-
    -
  • If the Query Term value target element corresponds to a Relationship,aListRelationshipor a VocabProperty and is a list of URIs e.g. color!=“http://example.com/black”, ” http://example.com/red”:
    • -
-
-
-
    -
  • The target value is not identical to any of the list values (e.g. matches “http://example.com/blue”).
    • -
  • The target value does not include any of the list values, if the target value is an array (e.g. matches [“http://example.com/blue”, “http://example.com/yellow”, “http://example.com/green”], but not [“http://example.com/blue”, “http://example.com/red”, “http://example.com/green”]).
    • -
-
-
-
    -
  • If the data type of the target value and the data type of the Query Term value are different, then they shall be considered unequal.
    • -
-
-
-
    -
  • Greater than operator (production rule named greater). For an entity to match, it shall contain the target element and the target value has to be strictly greater than the Query Term value:
    • -
-
-
-
    -
  • If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching.
    • -
-
-
-
    -
  • Less than operator (production rule named less). For an entity to match, it shall contain the target element and the target value shall be strictly less than the value:
    • -
-
-
-
    -
  • If there is no equality between the target value data type and the Query Term value data type then it shall be considered as not matching.
    • -
-
-
-
    -
  • Greater or equal than (production rule named greaterEq). A matching entity shall meet any of the Greater than or the Equal conditions for single values.
    • -
  • Less or equal than (production rule named lessEq). A matching entity shall meet any of the Less than or the Equal conditions for single values.
    • -
  • Match pattern (production rule named patternOp). A matching entity shall contain the target element and the target value shall be in the L(R) of the regular pattern specified by the Query Term:
    • -
-
-
-
    -
  • If the target value data type is different than String then it shall be considered as not matching.
    • -
-
-
-
    -
  • Do not match pattern (production rule named notPatternOp). A matching entity shall contain the target element and the target value shall not be in the L(R) of the regular pattern specified by the Query Term:
    • -
-
-
-
    -
  • If the target value data type is different than String then it shall be considered as not matching.
    • -
-
-

4.10 NGSI-LD Geoquery Language

-

The NGSI-LD Geoquery language shall be supported by implementations. It is intended to define predicates which allow testing whether a specific topological spatial relationship exists between a pair of geometries: a target geometry and a reference geometry. The target geometry represents a geospatial Property of an Entity, typically, the location of the Entity.

-

A total of four parameters are defined in order to fully specify an NGSI-LD Geoquery:

-
-
    -
  • georel, to express the desired geospatial relationship;
    • -
  • geometry, to express the type of the reference geometry;
    • -
  • coordinates, to express the reference geometry;
    • -
  • geoproperty, to express the target geometry of an Entity. This parameter is optional, location is the default.
    • -
-
-

The following grammar defines the syntax for the geospatial relationships (parameter name georel):

-
andOp = %x3B ; ;
-equal = %x3D %x3D ; ==
-georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel
-/ equalsRel / disjointRel
-nearRel = nearOp andOp distance equal PositiveNumber ;
-near;max(min)Distance==x (in meters)
-distance = "maxDistance" / "minDistance"
-nearOp = "near"
-withinRel = "within"
-containsRel = "contains"
-intersectsRel = "intersects"
-equalsRel = "equals"
-disjointRel = "disjoint"
-overlapsRel = "overlaps"
-

PositiveNumber shall be a non-zero positive number as mandated by the JSON Specification. Thus, it shall follow the ABNF Grammar, production rule named Number, section 6 of IETF RFC 8259 [6], excluding the ‘minus’ symbol and excluding the number 0.

-

Reference geometries shall be specified by:

-
-
    -
  • A geometry type (parameter name geometry) as defined by the GeoJSON specification (IETF RFC 7946 [8], section 1.4), except GeometryCollection.
    • -
  • A coordinates (parameter name coordinates) element which shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [8], section 3.1.1.
    • -
-
-

Target geometry, i.e. the target Entity’s GeoProperty to which the geoquery is to be applied, can be specified by an extra parameter named geoproperty. The GeoProperty’s name shall be specified as short hand name and not a fully qualified one, because, when the query language is used, an @context properly defining all the terms (as per clause 5.5.7) shall be issued. If no geoproperty is specified, the geoquery is applied to the default Property location (see clause 4.7.1).

-

Note that proper URL encoding shall be used by HTTP binding API clients when using these examples.

-
-
-

EXAMPLE 1:

-
-
-

?georel=near;maxDistance==2000

-
&geometry=Point
-&coordinates=[8,40]
-&geoproperty=observationSpace
-
-
-
-
-

EXAMPLE 2:

-
-
-

?georel=within

-
&geometry=Polygon
-&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],
-[100.0,0.0]]]
-&geoproperty=location
-
-
-
-
-

EXAMPLE 3:

-
-
-

A query encoded as an HTTP Query String. Note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2 .

-
&geometry=Point
-&coordinates=[8,40]
-
-
-

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

-
-
    -
  • near statement (production rule named nearRel):
    • -
-
-
-
    -
  • maxDistance modifier. For an entity to match it has to be within the buffer geometric object (as defined by [14]) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named PositiveNumber).
    • -
  • minDistance modifier. For an entity to match it has to be disjoint with the buffer geometric object (as defined by [14]) given by the reference geometry, with distance (in meters) equal to the number conveyed (production rule named PositiveNumber).
    • -
-
-
-
    -
  • equals relationship (production rule named equalsRel). For an entity to match, the target geometry shall be equal, as specified by [14], to the reference geometry.
    • -
  • disjoint relationship (production rule named disjointRel). For an entity to match, the target geometry shall be disjoint, as specified by [14], to the reference geometry.
    • -
  • intersects relationship (production rule named intersectsRel). For an entity to match, the target geometry shall intersect, as specified by [14], with the reference geometry.
    • -
  • within relationship (production rule named withinRel). For an entity to match, the target geometry shall be within, as specified by [14], the reference geometry.
    • -
  • contains relationship (production rule named containsRel). For an entity to match, the target geometry shall contain, as specified by [14], the reference geometry.
    • -
  • overlaps relationship (production rule named overlapsRel). For an entity to match, the target geometry shall overlap, as specified by [14], the reference geometry.
    • -
-
-

When resolving geo-queries, Entities which do not convey the target GeoProperty of the query shall be considered as non-matching.

-

4.11 NGSI-LD Temporal Query Language

-

The NGSI-LD Temporal Query language shall be supported by implementations. It is intended to define predicates which allow testing whether Temporal Properties of NGSI-LD Entities, Properties and Relationships, are within certain temporal constraints. In particular it can be used to request historic Property values and Relationships that were valid within the specified timeframe.

-

The following grammar defines the syntax that shall be supported:

-
timerel = beforeRel / afterRel / betweenRel
-beforeRel = "before"
-afterRel = "after"
-betweenRel = "between"
-

The points in time for comparison are defined as follows:

-
-
    -
  • A timeAt parameter, which shall represent the comparison point for the before and after relation and the starting point for the between relation. It shall be represented as DateTime (mandated by clause 4.6.3).
    • -
  • An endTimeAt parameter, which is only used for the between relation and shall represent the end point for comparison. It shall be represented as DateTime (mandated by clause 4.6.3).
    • -
-
-

The Temporal Property (see clause 4.8) to which the temporal query is to be applied can be specified by timeproperty. If no timeproperty is specified, the temporal query is applied to the default Temporal Property observedAt.

-
-
-

EXAMPLE 1:

-
-
-

?timerel=before

-
-
-
-
-

&timeAt=2017-12-13T14:20:00Z

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

?timerel=between

-
&timeAt=2017-12-13T14:20:00Z
-&endTimeAt=2017-12-13T14:40:00Z
-&timeproperty=modifiedAt
-
-
-
-
-

EXAMPLE 3:

-
-
-

Temporal query encoded as HTTP Query String, note that this is HTTP binding specific, to be used via GET method, as defined in clause 6.18.3.2 .

-
&timeproperty=observedAt
-&timeAt=2017-12-13T14:20:00Z
-
-
-

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

-
-
    -
  • before relationship (production rule named beforeRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be before the time specified by timeAt. The specified value is used as an exclusive bound in the Temporal Query;
    • -
  • after relationship (production rule named afterRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be after the time specified by timeAt. The specified value is used as an inclusive bound in the Temporal Query;
    • -
  • between relationship (production rule named betweenRel). For a Temporal Property to match, the value of the specified Temporal Property (or observedAt as default) has to be after the time specified by timeAt and before the time specified by endTimeAt. In the Temporal Query, the value specified for the lower bound of the range is inclusive and the value specified for the upper bound of the range is exclusive.
    • -
-
-

When resolving temporal queries, Entities which do not convey the target Temporal Property of the query shall be considered as non-matching.

-

4.12 NGSI-LD Pagination

-

NGSI-LD operations can potentially return a result set including a large number of NGSI-LD Elements, so that pagination of query results shall be supported by compliant implementations.

-

The list of operations that incur this behaviour is as follows:

-
- -
-

Nonetheless, the NGSI-LD API is agnostic about specific pagination mechanisms and only defines the behaviour that shall be observed by NGSI-LD Systems.

-

For each operation above, NGSI-LD Systems shall:

-
-
    -
  • provide a mechanism to iterate through the NGSI-LD Elements of a result set without exhausting NGSI-LD Client or Broker resources;
    • -
  • provide a mechanism to flag NGSI-LD Clients when there are remaining NGSI-LD Elements to be traversed as part of a result set;
    • -
  • allow NGSI-LD Clients specifying a limit (page size), as a parameter of API operations, to the number of NGSI-LD Elements (at a maximum) retrieved by the implementation for each pagination iteration;
    • -
  • define a default limit (default page size) to the number of NGSI-LD Elements retrieved per pagination iteration;
    • -
  • allow NGSI-LD Clients iterating forwards and backwards through a result set.
    • -
-
-

NGSI-LD implementations should:

-
-
    -
  • avoid Denial of Service attacks or other potential security risks, by defining a hard limit to the size of generated response payload body while paginating. For instance, certain queries can be rejected by issuing an error of type TooManyResults.
    • -
-
-

NGSI-LD implementations may:

-
-
    -
  • warn NGSI-LD Clients when result sets become invalid due to dynamic changes in NGSI-LD Elements (additions, deletions) occurred while iterating over pages.
    • -
-
-

The concrete realization of the features described above might depend on each API binding. Nonetheless, NGSI-LD Systems shall implement pagination features as mandated by the present clause, for any API binding.

-

4.13 Counting the Number of Results

-

Given that NGSI-LD Query operations can potentially return a result set including a large number of NGSI-LD Elements and that pagination of query results shall be supported (see clause 4.12), compliant implementations shall also support a mechanism for relaying to the client the number of expected resulting elements, when a query is executed.

-

A specific field (e.g. a custom header in the response in case of HTTP binding, see clause 6.3.13) shall be returned within the response of a query, whenever this is requested by the client.

-

Mechanisms for limiting the number of returned NGSI-LD Elements are independent of the counting mechanism, so that, potentially, a client can issue a query that limits to zero the number of desired results but asks for the count to be present.

-

This is useful for client-side planning and fine-tuning of subsequent queries and their parameters.

-

4.14 Supporting Multiple Tenants

-

The concept of a Tenant is that a user or group of users utilizes a single instance of an NGSI-LD system (Context Source or Context Broker) in isolation from other users or groups of users of the same instance, which are considered to be different Tenants. Thus a multi-tenant NGSI-LD system is a system where a single software instance is used by different users or groups of users, the Tenants, where 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. Typically, multi-tenancy is used together with an access control mechanism, enforcing the isolation of Tenants, however access control and other security-related aspects are out-of-scope of the present document.

-

The NGSI-LD API optionally enables multi-tenant systems. To support this, Tenant information can be optionally specified in NGSI-LD API operations. The operation then only applies to the targeted Tenant. As all information of one Tenant is isolated from other Tenants, the NGSI-LD API operations for managing, retrieving and subscribing to entity information, but also any context source related operations only apply to the information of the specified Tenant in isolation and never have any effect on the information of other Tenants.

-

As the support and use of Tenants is optional, any operation not explicitly specifying a Tenant targets a default Tenant, which always exists. NGSI-LD systems not supporting multiple Tenants should raise an error of type NoMultiTenantSupport if a Tenant is specified. To enable Context Sources to be part of tenant-based distributed or federated systems, Tenant information can optionally be specified in Context Source Registrations. When contacting the respective Context Sources, the Tenant information from the Context Source Registration has to be used. If no Tenant information is present in the Context Source Registration, no Tenant information is to be used and thus the default Tenant is targeted on the registered Context Source. This enables integrating Context Sources not supporting multi-tenancy in a distributed system with a Tenant-based Context Broker or integrating local Tenants in a federated system using a different Tenant.

-

4.15 NGSI-LD Language Filter

-

The NGSI-LD Language Filter shall be supported by implementations. It is intended to form a mechanism which allows just one matching string value of LanguageProperties of NGSI-LD Entities to be converted to an NGSI-LD Property, where the value will be a string for the specified natural language.

-

The following grammar defines the syntax that shall be supported by the filter:

-
lang = langtag
-

Where the langtag is defined according to the rules as mandated by IETF RFC 5646 [28], and IETF RFC 3282 [29]. If the Context Broker cannot serve any matching language, it shall default to any supported language. This behavior can be triggered by specifying lang=“*”in the filter (see example 3).

-

In any case, the attribute in question shall be augmented with an additional non-reified subproperty lang indicating the actual language returned.

-
-
-

EXAMPLE 1:

-
-
-

Specified natural language - return LanguageProperties as strings in English only.

-
-
-
-
-

lang=“en”

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Multiple natural languages with no ranked preference - return LanguageProperties as strings in either Swiss French or French.

-
-
-
-
-

lang=“fr-CH,fr”

-
-
-
-
-
-
-

EXAMPLE 3:

-
-
-

Wildcard - return LanguageProperties as a string in any supported language.

-
-
-
-
-

lang=“*”

-
-
-
-
-
-
-

EXAMPLE 4:

-
-
-

Quality value ranking - return all LanguageProperties as a string in Swiss French or French with no ranked preference, fallback to English as a second choice and finally fallback to any other supported language.

-
-
-
-
-

lang=“fr-CH,fr;q=0.9,en;q=0.8,*;q=0.5”

-
-
-
-
-

4.16 Supporting Multiple Entity Types

-

From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any Entity are supported. An Entity is uniquely identified by its id, so whenever information is provided for an Entity with a given id, it is considered part of the same Entity, regardless of the Entity Type(s) specified. To avoid unexpected behaviour, Entity Types can be implicitly added by all operations that update or append attributes. There is no operation to remove Entity Types from an Entity. The philosophy here is to assume that an Entity always had all Entity Types, but possibly not all Entity Types have previously been known in the system. The only option to remove an Entity Type is to delete the Entity and re-create it with the same id. Alternatively, a batch upsert with ‘replace’ update mode can be used, as described in clause 5.6.8.

-

4.17 NGSI-LD Entity Type Selection Language

-

The NGSI-LD Entity Type Selection Language shall be supported by implementations. It is intended to select only those Entities that have the specified Entity Type(s), possibly among others. Entity Types are specified as a disjunction of elements, where each element can either directly be an Entity Type or a conjunction of multiple Entity Types. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Entity Types can also be seen as a list, and to be compatible with previous versions of the NGSI-LD API, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

-
EntityTypes = OrEntityType *(orOp OrEntityType)         ; OrEntityType|OrEntityType
-OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType)
-OrEntityType = EntityType                               ; EntityType
-andOp = %x3B                                ; ;
-orOp = %x7C / %x2C                                                  ; |  ,
-

EntityType is either a valid name as specified in clause 4.6.2 or a URI.

-
-
-

EXAMPLE 1:

-
-
-

Entities of type Building or House:

-
-
-
-
-

Building|House

-
-
-
-
-
-
-

Building,House

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Entities of type Home and Vehicle:

-
-
-
-
-

(Home;Vehicle)

-
-
-
-
-
-
-

EXAMPLE 3:

-
-
-

Entities of type (Home and Vehicle) or Motorhome:

-
-
-
-
-

(Home;Vehicle)|Motorhome

-
-
-
-
-
-
-

(Home;Vehicle),Motorhome

-
-
-
-
-
-
-

NOTE:

-
-
-

The special characters “,” , “;” , “(” and “)” used in the Entity Type Selection Language are allowed characters in URIs. The use of short names is recommended.

-
-
-

4.18 NGSI-LD Scopes

-

An NGSI-LD Scope enables putting Entities into a hierarchical structure and restrict results of queries and notifications accordingly. The hierarchical structure is user-defined, e.g. according to (logical) location or organization. The use of Scopes is optional and an Entity can be assigned to one or more Scopes at the same time. The Scope is represented as a special scope Property that is non-reified in the normalized Entity representation and reified in the temporal representation of an Entity. In the latter case, it is restricted to having the non-reified Temporal Properties createdAt, modifiedAt and deletedAt as sub-Properties. There shall at most be one instance of the scope property per Entity. In case multiple representations of the same Entity have to be merged, e.g. when combining the results of distributed queries, the values of scope are merged. The value of scope is represented as a JSON array in case there is more than one Scope. For the Temporal Evolution a given Scope is considered valid from the time it has been set until the time it has been explicitly removed by an update or delete operation (for an example see annex C, clause C.5.16).

-

The grammar that encodes the syntax of the Scope is expressed in ABNF format [12]. It is described below (it has been validated using <https://github.com/ietf-tools/bap>), and it shall be supported by implementations. The special string “urn:ngsi-ld:null” (i.e. the NGSI-LD Null) shall be only used and only appear in case of deleted scopes.

-
Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)              ; [/] ScopeLevel *(/ScopeLevel)
-Scope =/ "urn:ngsi-ld:null"                               ; the literal string "urn:ngsi-ld:null"
-ScopeLevel = unicodeLetter *ScopeLevelChar
-ScopeLevelChar = unicodeNumber / unicodeLetter
-ScopeLevelChar =/ %x5F                                    ; _
-
-
-

EXAMPLE 1:

-
-
-

/Madrid

-
-
-
-
-

EXAMPLE 2:

-
-
-

Madrid

-
-
-
-
-

EXAMPLE 3:

-
-
-

/Madrid/Gardens/ParqueNorte

-
-
-
-
-

EXAMPLE 4:

-
-
-

/CompanyA/OrganizationB/UnitC

-
-
-

4.19 NGSI-LD Scope Query Language

-

The NGSI-LD Scope Query Language shall be supported by implementations. It is intended to select only those Entities that are within the specified Scope(s). Scopes are specified as a disjunction of elements, where each element can either directly be a Scope or a conjunction of multiple Scopes. The “+” can be used as a wildcard to match a single scope level within a Scope. The “#” that can be added at the end of a Scope specification serves as a wildcard, which matches the given scope and the whole hierarchy of scopes below. The “/#” matches any non-empty scope, i.e. only explicitly specified scopes. The logical operators are the same as in the NGSI-LD Query Language specified in clause 4.9. As a disjunction of Scopes can also be seen as a list, a comma can be used as an alternative representation of the or operator. For logical and grouping parenthesis are needed.

-
ScopesQ = OrScopeQ *(orOp OrScopeQ)         ; OrScopeQ|OrScopeQ
-ScopesQ =/ %x2F %23             ; / #
-OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29                 ; (ScopeQ;ScopeQ)
-OrScopeQ =/ ScopeQ *1(%x2F %23)                             ; ScopeQ / #
-andOp = %x3B                                ; ;
-orOp = %x7C / %x2C                                                  ; |  ,
-ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel)
-ScopeQLevel = unicodeLetter *ScopeQLevelChar
-ScopeQLevel =/ %x2B             ; + 
-ScopeQLevelChar = unicodeNumber / unicodeLetter
-ScopeQLevelChar =/ %x5F                                             ; _
-
-
-

EXAMPLE 1:

-
-
-

Scope /Madrid:

-
-
-
-
-

/Madrid

-
-
-
-
-
-
-

EXAMPLE 2:

-
-
-

Scope /Madrid/Gardens and the whole scope tree below:

-
/Madrid/Gardens/#,
-/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur
-
-
-
-
-

EXAMPLE 3:

-
-
-

Scopes /Madrid/Gardens/ParqueNorte and /Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first scope level and ParqueNorte as third scope level:

-
-
-
-
-

/Madrid/+/ParqueNorte

-
-
-
-
-
-
-

EXAMPLE 4:

-
-
-

Scope /Madrid/Districts and /CompanyA:

-
-
-
-
-

(/Madrid/Districts;/CompanyA)

-
-
-
-
-
-
-

EXAMPLE 5:

-
-
-

Scope (/Madrid/Districts and /CompanyA) or /CompanyB:

-
-
-
-
-

(/Madrid/Districts;/CompanyA)|CompanyB

-
-
-
-
-
-
-

(/Madrid/Districts;/CompanyA),CompanyB

-
-
-
-
-

4.20 NGSI-LD Distributed Operation names

-

When registering Context Sources (see clause 5.2.9), the registrant NGSI-LD interface endpoint may optionally offer a subset of NGSI-LD operations which it accepts. Table 4.20‑1 defines a list of names for each of these operations.

-
-

Table 4.20-1: Names of implemented Operations

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Operation name -
-Implements -
-
-Context Information Provision -
-createEntity -
-5.6.1 Create Entity -
-updateEntity -
-5.6.2 Update Attributes -
-appendAttrs -
-5.6.3 Append Attributes -
-updateAttrs -
-5.6.4 Partial Attribute update -
-deleteAttrs -
-5.6.5 Delete Attribute -
-deleteEntity -
-5.6.6 Delete Entity -
-createBatch -
-5.6.7 Batch Entity Creation -
-upsertBatch -
-5.6.8 Batch Entity Creation or Update (Upsert) -
-updateBatch -
-5.6.9 Batch Entity Update -
-deleteBatch -
-5.6.10 Batch Entity Delete -
-upsertTemporal -
-5.6.11 Create or Update Temporal Evolution of an Entity -
-appendAttrsTemporal -
-5.6.12 Add Attributes to Temporal Evolution of an Entity -
-deleteAttrsTemporal -
-5.6.13 Delete Attributes from Temporal Evolution of an Entity -
-updateAttrInstanceTemporal -
-5.6.14 Partial Update Attribute Instance in Temporal Evolution of an Entity -
-deleteAttrInstanceTemporal -
-5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity -
-deleteTemporal -
-5.6.16 Delete Temporal Evolution of an Entity -
-mergeEntity -
-5.6.17 Merge Entity -
-replaceEntity -
-5.6.18 Replace Entity -
-replaceAttrs -
-5.6.19 Replace Attribute -
-mergeBatch -
-5.6.20 Batch Entity Merge -
-purgeEntity -
-5.6.21 Purge Entities -
-Context Information Consumption -
-retrieveEntity -
-5.7.1 Retrieve Entity -
-queryEntity -
-5.7.2 Query Entities (excluding batch entity queries) -
-queryBatch -
-5.7.2 Query Entities (batch entity queries only) -
-retrieveTemporal -
-5.7.3 Retrieve Temporal Evolution of an Entity -
-queryTemporal -
-5.7.4 Query Temporal Evolution of Entities -
-retrieveEntityTypes -
-5.7.5 Retrieve Available Entity Types -
-retrieveEntityTypeDetails -
-5.7.6 Retrieve Details of Available Entity Types -
-retrieveEntityTypeInfo -
-5.7.7 Retrieve Available Entity Type Information -
-retrieveAttrTypes -
-5.7.8 Retrieve Available Attributes -
-retrieveAttrTypeDetails -
-5.7.9 Retrieve Details of Available Attributes -
-retrieveAttrTypeInfo -
-5.7.10 Retrieve Available Attribute Information -
-Context Information Subscription -
-createSubscription -
-5.8.1 Create Subscription -
-updateSubscription -
-5.8.2 Update Subscription -
-retrieveSubscription -
-5.8.3 Retrieve Subscription -
-querySubscription -
-5.8.4 Query Subscription -
-deleteSubscription -
-5.8.5 Delete Subscription -
-Support operations for distributed operations -
-retrieveEntityMap -
-5.14.1 Retrieve EntityMap -
-updateEntityMap -
-5.14.2 Update EntityMap -
-deleteEntityMap -
-5.14.3 Delete EntityMap -
-createEntityMapQueryEntity -
-5.14.4 Create EntityMap for Query Entities -
-createEntityMapQueryTemporal -
-5.14.5 Create EntityMap for Query Temporal Evolution of Entities -
-retrieveContextSourceIdentity -
-5.15.1 Retrieve Context Source Identity Information -
-

In addition to these individual operations, a series of names for common groups of operations have also been defined. Table 4.20‑2 defines a list of names for each of these operation groups.

-
-

Table 4.20-2: Named Operation Groups

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Operation Group name -
-Implements -
-federationOps -
-
    -
  • retrieveEntity
    • -
  • queryEntity
    • -
  • queryBatch
    • -
  • retrieveEntityTypes
    • -
  • retrieveEntityTypeDetails
    • -
  • retrieveEntityTypeInfo
    • -
  • retrieveAttrTypes
    • -
  • retrieveAttrTypeDetails
    • -
  • retrieveAttrTypeInfo
    • -
  • createSubscription
    • -
  • updateSubscription
    • -
  • retrieveSubscription
    • -
  • querySubscription
    • -
  • deleteSubscription
    • -
  • retrieveEntityMap
    • -
  • updateEntityMap
    • -
  • deleteEntityMap
    • -
  • createEntityMapQueryEntity
    • -
  • retrieveContextSourceIdentity
    • -
-
-associationOps -
-updateOps -
-
    -
  • updateEntity
    • -
  • updateAttrs
    • -
  • replaceEntity
    • -
  • replaceAttrs
    • -
-
-retrieveOps -
-
    -
  • retrieveEntity
    • -
  • queryEntity
    • -
-
-redirectionOps -
-
    -
  • createEntity
    • -
  • updateEntity
    • -
  • appendAttrs
    • -
  • updateAttrs
    • -
  • deleteAttrs
    • -
  • deleteEntity
    • -
  • mergeEntity
    • -
  • replaceEntity
    • -
  • replaceAttrs
    • -
  • retrieveEntity
    • -
  • queryEntity
    • -
  • purgeEntity
    • -
  • retrieveEntityTypes
    • -
  • retrieveEntityTypeDetails
    • -
  • retrieveEntityTypeInfo
    • -
  • retrieveAttrTypes
    • -
  • retrieveAttrTypeDetails
    • -
  • retrieveAttrTypeInfo
    • -
  • retrieveEntityMap
    • -
  • updateEntityMap
    • -
  • deleteEntityMap
    • -
  • createEntityMapQueryEntity
    • -
  • retrieveContextSourceIdentity
    • -
-
-

If no specific subset of operations is defined for a Context Source Registration, the default set of operations matches the group defined as “federationOps”.

-

4.21 NGSI-LD Attribute Projection Language

-

The NGSI-LD Attribute Projection Language shall be supported by implementations for projection parameters (e.g. pick and omit). Its aim is to specify the Attributes to be retrieved within an Entity (or associated Linked Entities when Linked Entity Retrieval is used). Projected Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or in the case of Linked Entity Retrieval, a Relationship name followed by an Attribute name within the Linked Entity. Since a disjunction of Attributes is a list, either a comma or a pipe character can be used as alternative representations of the or operator. In the following, ABNF grammar for NGSI-LD Attribute Projection Language is given.

-
orOp = %x7C / %x2C                                                  ; |  ,
-ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm)
-LinkedEntityTerm  = %x7B ProjectionTerm %x7D        ; {ProjectionTerm}
-

See clause 4.9 for the definition of AttrName.

-
-
-

EXAMPLE 1:

-
-
-

?pick=temperature

-
-
-
-
-

EXAMPLE 2:

-
-
-

?pick=temperature,humidity

-
-
-
-
-

EXAMPLE 3:

-
-
-

?pick=observation{temperature,humidity}

-
-
-

4.22 Transient Storage of Entities and Attributes

-

In some cases, it is desirable to create an Entity (or Attribute) which is only expected to be stored for a defined period of time. Thereafter such an Entity (or Attribute) should be removed, and can be safely deleted from the context via an automatic garbage collection process.

-

In this regard NGSI-LD defines the following system Property of type TemporalProperty that shall be supported by implementations:

-
-
    -
  • expiresAt is defined as the system temporal Property at which a certain Entity, Property or Relationship shall become invalid and may be automatically removed from the Context Broker. For example, an Alert Entity was created to last for 24 hours and should be removed after this period of time.
    • -
-
-

It should be noted that clean-up processes will only run periodically, and will be dependent upon the Context Broker implementation, therefore final deletion will always lag the expiresAt timestamp to a certain extent. Furthermore, expiresAt only applies to the local storage, i.e. the Entity or Attribute is to be deleted locally, but not on other Context Sources or Context Broker hosting such Entity information, where no expiresAt timestamp is present. Thus expiresAt is not considered to be intrinsic to the Entity or Attribute, but only applies to the storage of the Entity or Attribute respectively. As it pertains to a system function (the deletion from storage after the expiration time), it is considered to be a system attribute.

-

4.23 Entity Ordering

-

4.23.1 Introduction

-

When a Context Consumer queries for Entities retrieved from a single context broker, it shall be possible to request that the array of Entities returned are ordered according to the values held within an Entity Attribute. Context Broker implementations shall interpret such requests and return the array of Entities sorted accordingly.

-

For each Attribute name listed, one of four types of sort order can be specified:

-
    -

  • Sort in ascending order by target value or target object

    • -

  • Sort in descending order by target value or target object

    • -

  • Sort by distance in ascending order from a specified GeoJSON geometry

    • -

  • Sort by distance in descending order from a specified GeoJSON geometry

    • -
-

When sorting by ascending or descending order, the preferred sort order for numbers and datetimes is trivial, however for strings the default collation order shall be defined as using ICU “root” collation order (“und-x-icu”) which returns a reasonable language-agnostic sort order (see IETF RFC 6067 [36]).

-

Sort by distance shall be limited to GeoProperties, and shall be defined as calculating spherical distance using the Haversine formula.

-

4.23.2 Datatype Comparison Order

-

When sorting by value, and the values of Attributes are of mixed datatypes, the following comparison order (null values last), shall be implicitly applied:

-
    -

  • Numbers

    • -

  • Strings

    • -

  • Object

    • -

  • Array

    • -

  • Boolean

    • -

  • Time

    • -

  • Date

    • -

  • DateTime

    • -

  • Null

    • -

  • Attribute does not exist

    • -
-

Additionally, when sorting by distance, the following comparison order, shall be applied:

-
    -

  • Attribute is a GeoProperty

    • -

  • Attribute is not a GeoProperty – sorted by value as shown above.

    • -
-

4.23.3 NGSI-LD Entity Ordering Language

-

The NGSI-LD Entity Ordering Language shall be supported by implementations for the order parameter (i.e. orderBy). Its aim is to specify the Attributes to be used when ordering an Array of Entities retrieved. Ordering Attributes are specified as a disjunction of elements, where each element can either directly be an Attribute name, or an Attribute name followed by a direction (either ascending or descending, where ascending shall be the default if not supplied). The comma character shall be used to separate the elements to be used for ordering which shall be applied sequentially.

-

In the following, ABNF grammar for NGSI-LD Entity Ordering Language is given.

-
thenOp = %x2C                                                    ; ,
-directionOp ::= asc | desc | dist-asc|
-dist-desc
-OrderingTerm = AttrName *1(DirectionTerm) *(thenOp OrderingTerm)
-DirectionTerm = %x3B directionOp.                                   ; ;
-

See clause 4.9 for the definition of AttrName.

-
-
-

EXAMPLE 1:

-
-
-

?orderBy=name – applies sort ordering to rank Entities in ascending order using the value of the name Attribute.

-
-
-
-
-

EXAMPLE 2:

-
-
-

?orderBy=name,age - applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by ascending order using the age Attribute.

-
-
-
-
-

EXAMPLE 3:

-
-
-

?orderBy=name,age;desc – applies sort ordering to rank Entities in ascending order using the value of the name Attribute and thereafter where multiple Entities have the same name , by descending order using the value of age Attribute.

-
-
-
-
-

EXAMPLE 4:

-
-
-

?orderBy=address[city] – applies sort ordering using a sub-item within a Property Value defined as a complex JSON object. The trailing path is [city] . It is used to refer to a particular subitem within the value of the address Property .

-
-
-
-
-

EXAMPLE 5:

-
-
-

?orderBy=name.observedAt – applies sort ordering based on 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.

-
-
-
-

When sorting data using a specific ICU collation order as defined by IETF RFC 6067 [36], the collation element (parameter name collation) shall represent the preferred ordering.

-
-
-
-

EXAMPLE 7:

-
-
-

?orderBy=name&collation=und-u-ks-identic – applies sort ordering to rank Entities in ascending order using the case insensitive value of the name Attribute.

-
-
-
-
-

EXAMPLE 8:

-
-
-

?orderBy=name&collation=de-u-co-phonebk – applies sort ordering to rank Entities in ascending order using the value of the name Attribute and sorted according to German phonebook collation ordering.

-
-
-
-

For sort by distance, the coordinates element (parameter name orderFrom) shall represent the coordinates of the reference geometry as mandated by IETF RFC 7946 [8], section 3.1.2.

-
-
-
-

EXAMPLE 9:

-
-
-

?orderBy=location;dist-asc&orderFrom=[8,40] – applies sort ordering to rank Entities in ascending distance from a Point with respect to the location GeoProperty .

-
-
-
-
-

EXAMPLE 10:

-
-
-

?orderBy=location;dist-desc&orderFrom=[8,40] – applies sort ordering to rank Entities in descending distance from a Point with respect to the location GeoProperty .

-
-
-
-
-

EXAMPLE 11:

-
-
-

?orderBy=location;dist-asc

-
&orderFrom=[[8,40],[9,42],[9,45],[8,40]]
-&orderGeometry=LineString
-
-
-
-

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.

-

If the key “contentType” is defined:

-

the value shall be a MIME type acceptable to the Context Broker (one of: “application/json”,“application/ld+json”) .

-

theContext Broker shall provide the request and the associated @context as required by the MIME type when distributing the request to the context source endpoint, regardless of how it was provided in the initial request.

-

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.

-
"ngsildConformance"
-1.5
-

the Context Broker shall apply a backwards compatibility operation over the payload (as defined by clause 4.3.6.8) prior to distributing the request to the context source endpoint such that the forwarded payload conforms to the specified version of the NGSI-LD specification

-
-
- - - - - diff --git a/API/index.html b/API/index.html deleted file mode 100644 index 77624591546c38423eafe3d67dca224c7c9c9ae3..0000000000000000000000000000000000000000 --- a/API/index.html +++ /dev/null @@ -1,1514 +0,0 @@ - - - - - - - -consolidated - - - - - - - - - - - - -
-
- - - - - diff --git a/API/media/image10.png b/API/media/image10.png deleted file mode 100644 index 6ffecf0fec9746b50cc36dbac8a7fd3f89395d7c..0000000000000000000000000000000000000000 Binary files a/API/media/image10.png and /dev/null differ diff --git a/API/media/image100.png b/API/media/image100.png deleted file mode 100644 index a167ecea4d3a4ba0e122c1f31185ec3a50bdd980..0000000000000000000000000000000000000000 Binary files a/API/media/image100.png and /dev/null differ diff --git a/API/media/image101.png b/API/media/image101.png deleted file mode 100644 index b5463e2c4d9a7d1f508d4a63ba8ed07cdddfd654..0000000000000000000000000000000000000000 Binary files a/API/media/image101.png and /dev/null differ diff --git a/API/media/image102.png b/API/media/image102.png deleted file mode 100644 index b99e300aa7f1ee7685209a7a3f3e087f17318ec1..0000000000000000000000000000000000000000 Binary files a/API/media/image102.png and /dev/null differ diff --git a/API/media/image103.png b/API/media/image103.png deleted file mode 100644 index 8688d01bc8eb636889410d9859c02ac915625ee0..0000000000000000000000000000000000000000 Binary files a/API/media/image103.png and /dev/null differ diff --git a/API/media/image104.png b/API/media/image104.png deleted file mode 100644 index 562b090b57f90a0dc857c4d30e6e3dd977bf6a96..0000000000000000000000000000000000000000 Binary files a/API/media/image104.png and /dev/null differ diff --git a/API/media/image105.png b/API/media/image105.png deleted file mode 100644 index 6aa18c0b14396b273b76fb65f9f108c91bf1ef10..0000000000000000000000000000000000000000 Binary files a/API/media/image105.png and /dev/null differ diff --git a/API/media/image106.png b/API/media/image106.png deleted file mode 100644 index 8d88258d142d47a901af7bf16d3580766f5acbed..0000000000000000000000000000000000000000 Binary files a/API/media/image106.png and /dev/null differ diff --git a/API/media/image107.png b/API/media/image107.png deleted file mode 100644 index e9da7a0e60f131d903e350576019c7319e355441..0000000000000000000000000000000000000000 Binary files a/API/media/image107.png and /dev/null differ diff --git a/API/media/image108.png b/API/media/image108.png deleted file mode 100644 index 951cd9db7ec0d1c63a9cf900e834bff4d2f92d42..0000000000000000000000000000000000000000 Binary files a/API/media/image108.png and /dev/null differ diff --git a/API/media/image109.png b/API/media/image109.png deleted file mode 100644 index 35ee29c59280fdc9eff71166078fafc1a0182916..0000000000000000000000000000000000000000 Binary files a/API/media/image109.png and /dev/null differ diff --git a/API/media/image11.png b/API/media/image11.png deleted file mode 100644 index 4a9e87eeb80202e2431ec75261f312c691ba76b0..0000000000000000000000000000000000000000 Binary files a/API/media/image11.png and /dev/null differ diff --git a/API/media/image110.png b/API/media/image110.png deleted file mode 100644 index e5014c79d6ee0b51fc644ee08696bdf21812e61a..0000000000000000000000000000000000000000 Binary files a/API/media/image110.png and /dev/null differ diff --git a/API/media/image111.emf b/API/media/image111.emf deleted file mode 100644 index d5ca33327bee43d226587903ea7d6378d293fcb1..0000000000000000000000000000000000000000 Binary files a/API/media/image111.emf and /dev/null differ diff --git a/API/media/image111.png b/API/media/image111.png deleted file mode 100644 index 20ad857b2415e606e656787367a737c35b2d62cc..0000000000000000000000000000000000000000 Binary files a/API/media/image111.png and /dev/null differ diff --git a/API/media/image112.emf b/API/media/image112.emf deleted file mode 100644 index 9ce87040b9d0ce6a2b8e1ec1be53960e7fbd9daf..0000000000000000000000000000000000000000 Binary files a/API/media/image112.emf and /dev/null differ diff --git a/API/media/image112.png b/API/media/image112.png deleted file mode 100644 index 20ad857b2415e606e656787367a737c35b2d62cc..0000000000000000000000000000000000000000 Binary files a/API/media/image112.png and /dev/null differ diff --git a/API/media/image113.png b/API/media/image113.png deleted file mode 100644 index fece363b67fbff39e48bbd7afbb3052b44065ab8..0000000000000000000000000000000000000000 Binary files a/API/media/image113.png and /dev/null differ diff --git a/API/media/image114.png b/API/media/image114.png deleted file mode 100644 index 397b75b6e67a69c05fd543dd7eb637093555e019..0000000000000000000000000000000000000000 Binary files a/API/media/image114.png and /dev/null differ diff --git a/API/media/image115.png b/API/media/image115.png deleted file mode 100644 index 44cd4d8d0420ddaaf6070cb64bad7a439c2b068d..0000000000000000000000000000000000000000 Binary files a/API/media/image115.png and /dev/null differ diff --git a/API/media/image116.png b/API/media/image116.png deleted file mode 100644 index 550c05a25fa8e39601e4b79abadb3abe8f8a2b6c..0000000000000000000000000000000000000000 Binary files a/API/media/image116.png and /dev/null differ diff --git a/API/media/image117.png b/API/media/image117.png deleted file mode 100644 index f3b63aecf3fbf3a76cfa45fb51968e9adf798e75..0000000000000000000000000000000000000000 Binary files a/API/media/image117.png and /dev/null differ diff --git a/API/media/image118.emf b/API/media/image118.emf deleted file mode 100644 index 2f4273da07c425748c156993131a89a9196dedb2..0000000000000000000000000000000000000000 Binary files a/API/media/image118.emf and /dev/null differ diff --git a/API/media/image118.png b/API/media/image118.png deleted file mode 100644 index 674544452e9580ff66baff56cd8d9ce43c82fc79..0000000000000000000000000000000000000000 Binary files a/API/media/image118.png and /dev/null differ diff --git a/API/media/image119.emf b/API/media/image119.emf deleted file mode 100644 index b3a8b4f73428047dc14cbc2d61db327dddbf8629..0000000000000000000000000000000000000000 Binary files a/API/media/image119.emf and /dev/null differ diff --git a/API/media/image119.png b/API/media/image119.png deleted file mode 100644 index 674544452e9580ff66baff56cd8d9ce43c82fc79..0000000000000000000000000000000000000000 Binary files a/API/media/image119.png and /dev/null differ diff --git a/API/media/image12.png b/API/media/image12.png deleted file mode 100644 index 4b9e0356b43589616106aac84f72741ea3a631c3..0000000000000000000000000000000000000000 Binary files a/API/media/image12.png and /dev/null differ diff --git a/API/media/image120.png b/API/media/image120.png deleted file mode 100644 index 4d7ea53b8ab70ae12c7237b32d1ccda33279a7b5..0000000000000000000000000000000000000000 Binary files a/API/media/image120.png and /dev/null differ diff --git a/API/media/image121.png b/API/media/image121.png deleted file mode 100644 index e883c0d35a8c8e497ca126960d332902671a7d93..0000000000000000000000000000000000000000 Binary files a/API/media/image121.png and /dev/null differ diff --git a/API/media/image122.png b/API/media/image122.png deleted file mode 100644 index 7943d37bf37d96a221faf28641325434af1633b3..0000000000000000000000000000000000000000 Binary files a/API/media/image122.png and /dev/null differ diff --git a/API/media/image123.png b/API/media/image123.png deleted file mode 100644 index 913c8c3d9a1eca33b337339db68660674248e198..0000000000000000000000000000000000000000 Binary files a/API/media/image123.png and /dev/null differ diff --git a/API/media/image124.png b/API/media/image124.png deleted file mode 100644 index b52b81548a1438ebb5a131065e02f608841503dd..0000000000000000000000000000000000000000 Binary files a/API/media/image124.png and /dev/null differ diff --git a/API/media/image125.png b/API/media/image125.png deleted file mode 100644 index f1b14319f006537977e01503b6b04ba94bbcbf8f..0000000000000000000000000000000000000000 Binary files a/API/media/image125.png and /dev/null differ diff --git a/API/media/image126.png b/API/media/image126.png deleted file mode 100644 index e72070dab65f20619ad7837166ab19482b1d62d1..0000000000000000000000000000000000000000 Binary files a/API/media/image126.png and /dev/null differ diff --git a/API/media/image127.png b/API/media/image127.png deleted file mode 100644 index f07b60168cc66fa8296a95f7d366838e303f1863..0000000000000000000000000000000000000000 Binary files a/API/media/image127.png and /dev/null differ diff --git a/API/media/image128.png b/API/media/image128.png deleted file mode 100644 index 30f06af357490ba2d64124d5fefdb3fd500dd17c..0000000000000000000000000000000000000000 Binary files a/API/media/image128.png and /dev/null differ diff --git a/API/media/image129.png b/API/media/image129.png deleted file mode 100644 index 8cc333c2117533afd889d058db51d4127a9cae0f..0000000000000000000000000000000000000000 Binary files a/API/media/image129.png and /dev/null differ diff --git a/API/media/image130.png b/API/media/image130.png deleted file mode 100644 index 16468f39c03f8a0185719a0e9db18de907875599..0000000000000000000000000000000000000000 Binary files a/API/media/image130.png and /dev/null differ diff --git a/API/media/image131.png b/API/media/image131.png deleted file mode 100644 index cd4427cf8ac30e77e958ef28a9a8bd5ec83e695b..0000000000000000000000000000000000000000 Binary files a/API/media/image131.png and /dev/null differ diff --git a/API/media/image132.png b/API/media/image132.png deleted file mode 100644 index c81599c12f0bdd09670670a083a333ee64cb4402..0000000000000000000000000000000000000000 Binary files a/API/media/image132.png and /dev/null differ diff --git a/API/media/image133.emf b/API/media/image133.emf deleted file mode 100644 index 6e5f13db14d017f2647ccbceb92e25a30d9d69e7..0000000000000000000000000000000000000000 Binary files a/API/media/image133.emf and /dev/null differ diff --git a/API/media/image133.png b/API/media/image133.png deleted file mode 100644 index 5f3d0a7663b4aaa6d6245d73e16a2781ae3db1f9..0000000000000000000000000000000000000000 Binary files a/API/media/image133.png and /dev/null differ diff --git a/API/media/image134.emf b/API/media/image134.emf deleted file mode 100644 index fddd20c5f210f98de6cd7a9f61bb5faca4d77cf1..0000000000000000000000000000000000000000 Binary files a/API/media/image134.emf and /dev/null differ diff --git a/API/media/image134.png b/API/media/image134.png deleted file mode 100644 index 5f3d0a7663b4aaa6d6245d73e16a2781ae3db1f9..0000000000000000000000000000000000000000 Binary files a/API/media/image134.png and /dev/null differ diff --git a/API/media/image135.emf b/API/media/image135.emf deleted file mode 100644 index 6c41d97924c0bb24cab2e17c37ce500b9e190281..0000000000000000000000000000000000000000 Binary files a/API/media/image135.emf and /dev/null differ diff --git a/API/media/image135.png b/API/media/image135.png deleted file mode 100644 index 5f3d0a7663b4aaa6d6245d73e16a2781ae3db1f9..0000000000000000000000000000000000000000 Binary files a/API/media/image135.png and /dev/null differ diff --git a/API/media/image136.emf b/API/media/image136.emf deleted file mode 100644 index 73cff782c5207c7519d1d5413c704a91605c63da..0000000000000000000000000000000000000000 Binary files a/API/media/image136.emf and /dev/null differ diff --git a/API/media/image136.png b/API/media/image136.png deleted file mode 100644 index 5f3d0a7663b4aaa6d6245d73e16a2781ae3db1f9..0000000000000000000000000000000000000000 Binary files a/API/media/image136.png and /dev/null differ diff --git a/API/media/image137.emf b/API/media/image137.emf deleted file mode 100644 index 80687eecafe76b0d107f325fc4a41dfabe9bdc69..0000000000000000000000000000000000000000 Binary files a/API/media/image137.emf and /dev/null differ diff --git a/API/media/image137.png b/API/media/image137.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image137.png and /dev/null differ diff --git a/API/media/image138.emf b/API/media/image138.emf deleted file mode 100644 index e71e0cc0bd92cf58ed137a9817c08f02c7d9e81f..0000000000000000000000000000000000000000 Binary files a/API/media/image138.emf and /dev/null differ diff --git a/API/media/image138.png b/API/media/image138.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image138.png and /dev/null differ diff --git a/API/media/image139.emf b/API/media/image139.emf deleted file mode 100644 index b2e14ec1d417d6dadef167073b001ce28e6625b8..0000000000000000000000000000000000000000 Binary files a/API/media/image139.emf and /dev/null differ diff --git a/API/media/image139.png b/API/media/image139.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image139.png and /dev/null differ diff --git a/API/media/image140.emf b/API/media/image140.emf deleted file mode 100644 index 9dbdb681c99a68580e329503bfcbe2853f0e9ad7..0000000000000000000000000000000000000000 Binary files a/API/media/image140.emf and /dev/null differ diff --git a/API/media/image140.png b/API/media/image140.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image140.png and /dev/null differ diff --git a/API/media/image141.emf b/API/media/image141.emf deleted file mode 100644 index f57a160207ac3b8725dadd00cabf7d7d050ad854..0000000000000000000000000000000000000000 Binary files a/API/media/image141.emf and /dev/null differ diff --git a/API/media/image141.png b/API/media/image141.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image141.png and /dev/null differ diff --git a/API/media/image142.emf b/API/media/image142.emf deleted file mode 100644 index c65a0739a55d719d114c37d3cad515ed7b70faae..0000000000000000000000000000000000000000 Binary files a/API/media/image142.emf and /dev/null differ diff --git a/API/media/image142.png b/API/media/image142.png deleted file mode 100644 index 4c39567a081e6e0fbb94bc9a3f1ea18dea90dfd4..0000000000000000000000000000000000000000 Binary files a/API/media/image142.png and /dev/null differ diff --git a/API/media/image143.png b/API/media/image143.png deleted file mode 100644 index 8630e90d6f17a3b4aef8425fe5094b99498c3cf5..0000000000000000000000000000000000000000 Binary files a/API/media/image143.png and /dev/null differ diff --git a/API/media/image144.png b/API/media/image144.png deleted file mode 100644 index bf82378f6a6bf43a8dfa04d3204c312c91cef529..0000000000000000000000000000000000000000 Binary files a/API/media/image144.png and /dev/null differ diff --git a/API/media/image145.png b/API/media/image145.png deleted file mode 100644 index 8c2f1e28948a0178e77c1465869081c1c0398502..0000000000000000000000000000000000000000 Binary files a/API/media/image145.png and /dev/null differ diff --git a/API/media/image146.png b/API/media/image146.png deleted file mode 100644 index 42c45705899e4ed2695f50be8d423bd22165bbff..0000000000000000000000000000000000000000 Binary files a/API/media/image146.png and /dev/null differ diff --git a/API/media/image147.png b/API/media/image147.png deleted file mode 100644 index aec7408c274d9585b7ac59f656ab3d459f015f33..0000000000000000000000000000000000000000 Binary files a/API/media/image147.png and /dev/null differ diff --git a/API/media/image16.emf b/API/media/image16.emf deleted file mode 100644 index dbb2b38088e0f5b84d15d887d9a21ce5d7e8e982..0000000000000000000000000000000000000000 Binary files a/API/media/image16.emf and /dev/null differ diff --git a/API/media/image16.png b/API/media/image16.png deleted file mode 100644 index b53582f083c5da0a433dbfd8b50e547929b88bd1..0000000000000000000000000000000000000000 Binary files a/API/media/image16.png and /dev/null differ diff --git a/API/media/image17.png b/API/media/image17.png deleted file mode 100644 index 74c6be09fa8831cc5a7333f86aa48e740d1801ed..0000000000000000000000000000000000000000 Binary files a/API/media/image17.png and /dev/null differ diff --git a/API/media/image18.png b/API/media/image18.png deleted file mode 100644 index c8d1629ef39f68c6b38e51c9a532a70cb81727ad..0000000000000000000000000000000000000000 Binary files a/API/media/image18.png and /dev/null differ diff --git a/API/media/image19.png b/API/media/image19.png deleted file mode 100644 index 1e8f57ebdd9fef5a45639b985ae0a42c9ca6abc0..0000000000000000000000000000000000000000 Binary files a/API/media/image19.png and /dev/null differ diff --git a/API/media/image2.png b/API/media/image2.png deleted file mode 100644 index 06cef5175d3ececeee1384688000cb7219556b35..0000000000000000000000000000000000000000 Binary files a/API/media/image2.png and /dev/null differ diff --git a/API/media/image20.png b/API/media/image20.png deleted file mode 100644 index b009d7d7dba85324b01b516a6b82f300976c04d2..0000000000000000000000000000000000000000 Binary files a/API/media/image20.png and /dev/null differ diff --git a/API/media/image21.png b/API/media/image21.png deleted file mode 100644 index 0ee53dc4d0485387b1f4fbd9df6e9cbc4afd632b..0000000000000000000000000000000000000000 Binary files a/API/media/image21.png and /dev/null differ diff --git a/API/media/image22.png b/API/media/image22.png deleted file mode 100644 index 22ffb4eaa606ee257b3277a536441fe868b40f5f..0000000000000000000000000000000000000000 Binary files a/API/media/image22.png and /dev/null differ diff --git a/API/media/image23.png b/API/media/image23.png deleted file mode 100644 index 909b8322ecc02c9bc4b503a0c67f108060166496..0000000000000000000000000000000000000000 Binary files a/API/media/image23.png and /dev/null differ diff --git a/API/media/image24.png b/API/media/image24.png deleted file mode 100644 index 615f9c0e2731789bd7d8421c6c7574ef86120bb3..0000000000000000000000000000000000000000 Binary files a/API/media/image24.png and /dev/null differ diff --git a/API/media/image25.png b/API/media/image25.png deleted file mode 100644 index 66c95cb0c9eb358ab0cfacf0893d1f0a107c36f9..0000000000000000000000000000000000000000 Binary files a/API/media/image25.png and /dev/null differ diff --git a/API/media/image26.emf b/API/media/image26.emf deleted file mode 100644 index 1218f389f50ea046a293249ab84f79d4056b370d..0000000000000000000000000000000000000000 Binary files a/API/media/image26.emf and /dev/null differ diff --git a/API/media/image26.png b/API/media/image26.png deleted file mode 100644 index 0bbeb701bc714a4bdeb1953a6d78a7e628187e06..0000000000000000000000000000000000000000 Binary files a/API/media/image26.png and /dev/null differ diff --git a/API/media/image27.png b/API/media/image27.png deleted file mode 100644 index f6cb3a15fa0c819e978ed4a64f90c5e5b023eb78..0000000000000000000000000000000000000000 Binary files a/API/media/image27.png and /dev/null differ diff --git a/API/media/image28.png b/API/media/image28.png deleted file mode 100644 index 9a5c9e4a2f15ce652ed16c5f26301f62a76d2cf3..0000000000000000000000000000000000000000 Binary files a/API/media/image28.png and /dev/null differ diff --git a/API/media/image29.png b/API/media/image29.png deleted file mode 100644 index 59a093e7d5a1e9d29e32627d84955fc6bbf7c226..0000000000000000000000000000000000000000 Binary files a/API/media/image29.png and /dev/null differ diff --git a/API/media/image3.png b/API/media/image3.png deleted file mode 100644 index 052334200d5159b86bdaf1d7ce4a636e8f5b73bc..0000000000000000000000000000000000000000 Binary files a/API/media/image3.png and /dev/null differ diff --git a/API/media/image30.png b/API/media/image30.png deleted file mode 100644 index fbbd2eb77da17a8317c56826ea5f4112fe4d7840..0000000000000000000000000000000000000000 Binary files a/API/media/image30.png and /dev/null differ diff --git a/API/media/image31.png b/API/media/image31.png deleted file mode 100644 index cc908cbf0c0965423b4e7e0115433616e057c3eb..0000000000000000000000000000000000000000 Binary files a/API/media/image31.png and /dev/null differ diff --git a/API/media/image32.png b/API/media/image32.png deleted file mode 100644 index 5f248461c597e06c704a5d704a151ca118a8e984..0000000000000000000000000000000000000000 Binary files a/API/media/image32.png and /dev/null differ diff --git a/API/media/image33.png b/API/media/image33.png deleted file mode 100644 index c18995f490d46154355b2f4a4c78761697f0dec5..0000000000000000000000000000000000000000 Binary files a/API/media/image33.png and /dev/null differ diff --git a/API/media/image34.png b/API/media/image34.png deleted file mode 100644 index 6963f6e2b107868f7089524a841678c75ff4514b..0000000000000000000000000000000000000000 Binary files a/API/media/image34.png and /dev/null differ diff --git a/API/media/image35.png b/API/media/image35.png deleted file mode 100644 index 093c118c8ac4363f0d9faf03cd1f71420e33f749..0000000000000000000000000000000000000000 Binary files a/API/media/image35.png and /dev/null differ diff --git a/API/media/image36.emf b/API/media/image36.emf deleted file mode 100644 index 6b7a8c64451a8c4569f8086dea88385b8ea3c51b..0000000000000000000000000000000000000000 Binary files a/API/media/image36.emf and /dev/null differ diff --git a/API/media/image36.png b/API/media/image36.png deleted file mode 100644 index 9688731415f8f45bcaef6713355d17f0e82829d4..0000000000000000000000000000000000000000 Binary files a/API/media/image36.png and /dev/null differ diff --git a/API/media/image37.png b/API/media/image37.png deleted file mode 100644 index 47a302de6b5ef7f949ad4d03013cb6f3ac476f74..0000000000000000000000000000000000000000 Binary files a/API/media/image37.png and /dev/null differ diff --git a/API/media/image38.png b/API/media/image38.png deleted file mode 100644 index f647a8ca1196501d912d7cc6f5bfe81d5ac21d76..0000000000000000000000000000000000000000 Binary files a/API/media/image38.png and /dev/null differ diff --git a/API/media/image39.png b/API/media/image39.png deleted file mode 100644 index 1a777495320fe6cc581b2e840820212f2af83460..0000000000000000000000000000000000000000 Binary files a/API/media/image39.png and /dev/null differ diff --git a/API/media/image40.png b/API/media/image40.png deleted file mode 100644 index 7b2ac0963af97b383b533e61546387dbc1fac57b..0000000000000000000000000000000000000000 Binary files a/API/media/image40.png and /dev/null differ diff --git a/API/media/image41.png b/API/media/image41.png deleted file mode 100644 index 3ceb37c9389da5d3cc77b26f2449185917e4e2bf..0000000000000000000000000000000000000000 Binary files a/API/media/image41.png and /dev/null differ diff --git a/API/media/image42.png b/API/media/image42.png deleted file mode 100644 index 542373a1e49bea85d27cebe25d4e92488c61a402..0000000000000000000000000000000000000000 Binary files a/API/media/image42.png and /dev/null differ diff --git a/API/media/image43.png b/API/media/image43.png deleted file mode 100644 index 0259f5bf5873752e826ceff605ec10d1f94958f5..0000000000000000000000000000000000000000 Binary files a/API/media/image43.png and /dev/null differ diff --git a/API/media/image44.png b/API/media/image44.png deleted file mode 100644 index ab52eabba8eedc8f351fd06d7ea68027cd52915e..0000000000000000000000000000000000000000 Binary files a/API/media/image44.png and /dev/null differ diff --git a/API/media/image45.png b/API/media/image45.png deleted file mode 100644 index 73f77a682d354502dadaee977881d73927b419c4..0000000000000000000000000000000000000000 Binary files a/API/media/image45.png and /dev/null differ diff --git a/API/media/image46.png b/API/media/image46.png deleted file mode 100644 index e6e35fb1dcbfd236dccdd6d21e635204a0424034..0000000000000000000000000000000000000000 Binary files a/API/media/image46.png and /dev/null differ diff --git a/API/media/image47.png b/API/media/image47.png deleted file mode 100644 index 533e08bdab315bfe95dbd07c484a101aa89c9c80..0000000000000000000000000000000000000000 Binary files a/API/media/image47.png and /dev/null differ diff --git a/API/media/image48.png b/API/media/image48.png deleted file mode 100644 index e5e5eb73f6c82d7112148768ef2e20c8831a65b5..0000000000000000000000000000000000000000 Binary files a/API/media/image48.png and /dev/null differ diff --git a/API/media/image49.png b/API/media/image49.png deleted file mode 100644 index 2f6686bb0a8db1d458e84c3c5d382ff34f987f29..0000000000000000000000000000000000000000 Binary files a/API/media/image49.png and /dev/null differ diff --git a/API/media/image50.png b/API/media/image50.png deleted file mode 100644 index 419c8d61fe7c36096bac83456ed6bfbe81e6e8d3..0000000000000000000000000000000000000000 Binary files a/API/media/image50.png and /dev/null differ diff --git a/API/media/image51.png b/API/media/image51.png deleted file mode 100644 index 03ad855f9ae6911ff29a389e940d4906a205fb6b..0000000000000000000000000000000000000000 Binary files a/API/media/image51.png and /dev/null differ diff --git a/API/media/image52.png b/API/media/image52.png deleted file mode 100644 index 556b8b85b34b877ab1d1fcae1f533dfd317d467a..0000000000000000000000000000000000000000 Binary files a/API/media/image52.png and /dev/null differ diff --git a/API/media/image53.png b/API/media/image53.png deleted file mode 100644 index 0323a88f0d76e8580ac19a3c08dbe118d4b8553f..0000000000000000000000000000000000000000 Binary files a/API/media/image53.png and /dev/null differ diff --git a/API/media/image54.png b/API/media/image54.png deleted file mode 100644 index 9e292c7993e0c32e4472048ad4ac8046538e9f38..0000000000000000000000000000000000000000 Binary files a/API/media/image54.png and /dev/null differ diff --git a/API/media/image55.png b/API/media/image55.png deleted file mode 100644 index 1c137a3b8b4a8079eb67e1ff1e52f1a42decdac3..0000000000000000000000000000000000000000 Binary files a/API/media/image55.png and /dev/null differ diff --git a/API/media/image56.png b/API/media/image56.png deleted file mode 100644 index d69b010a8a781b5cd00cbdc77e15f4b0b6e59b30..0000000000000000000000000000000000000000 Binary files a/API/media/image56.png and /dev/null differ diff --git a/API/media/image57.png b/API/media/image57.png deleted file mode 100644 index 3baea89c97c58af5a539a74cbe86c7034c267a3a..0000000000000000000000000000000000000000 Binary files a/API/media/image57.png and /dev/null differ diff --git a/API/media/image58.png b/API/media/image58.png deleted file mode 100644 index 0342d37d0a50d8e454c5610ddc0a97af2abe44bc..0000000000000000000000000000000000000000 Binary files a/API/media/image58.png and /dev/null differ diff --git a/API/media/image59.png b/API/media/image59.png deleted file mode 100644 index d4280ac460530e4a122e0fa23c1eef614badc80b..0000000000000000000000000000000000000000 Binary files a/API/media/image59.png and /dev/null differ diff --git a/API/media/image60.png b/API/media/image60.png deleted file mode 100644 index 807b727c2e6ab2043ead4523aa117a88317cceab..0000000000000000000000000000000000000000 Binary files a/API/media/image60.png and /dev/null differ diff --git a/API/media/image61.png b/API/media/image61.png deleted file mode 100644 index 1e5019f6b4ce77ce38c9359498f137d2af057800..0000000000000000000000000000000000000000 Binary files a/API/media/image61.png and /dev/null differ diff --git a/API/media/image62.png b/API/media/image62.png deleted file mode 100644 index 9c2651584796e67ba2c075bf0dde4e214db33e61..0000000000000000000000000000000000000000 Binary files a/API/media/image62.png and /dev/null differ diff --git a/API/media/image63.png b/API/media/image63.png deleted file mode 100644 index db7f19b0ba455bdafbd74b0020e8f25f2a7e9349..0000000000000000000000000000000000000000 Binary files a/API/media/image63.png and /dev/null differ diff --git a/API/media/image64.png b/API/media/image64.png deleted file mode 100644 index df04ffa39f2745caf6ed799f46d36ba887e9982e..0000000000000000000000000000000000000000 Binary files a/API/media/image64.png and /dev/null differ diff --git a/API/media/image65.png b/API/media/image65.png deleted file mode 100644 index f52bf13eafdbeddf49f6e23901360b1b37f12cbf..0000000000000000000000000000000000000000 Binary files a/API/media/image65.png and /dev/null differ diff --git a/API/media/image66.emf b/API/media/image66.emf deleted file mode 100644 index 272b8db855b77ac1c401afb506e360e0648a572b..0000000000000000000000000000000000000000 Binary files a/API/media/image66.emf and /dev/null differ diff --git a/API/media/image66.png b/API/media/image66.png deleted file mode 100644 index 46a0ec1eeb13926aa33cdac3600e4ca7d115e447..0000000000000000000000000000000000000000 Binary files a/API/media/image66.png and /dev/null differ diff --git a/API/media/image67.emf b/API/media/image67.emf deleted file mode 100644 index 6cab8ced9504b975e085c17c93100923b8516300..0000000000000000000000000000000000000000 Binary files a/API/media/image67.emf and /dev/null differ diff --git a/API/media/image67.png b/API/media/image67.png deleted file mode 100644 index 46a0ec1eeb13926aa33cdac3600e4ca7d115e447..0000000000000000000000000000000000000000 Binary files a/API/media/image67.png and /dev/null differ diff --git a/API/media/image68.png b/API/media/image68.png deleted file mode 100644 index ac3381d55721664eed3c1b454c2f964e0ca88bd0..0000000000000000000000000000000000000000 Binary files a/API/media/image68.png and /dev/null differ diff --git a/API/media/image69.emf b/API/media/image69.emf deleted file mode 100644 index bb347947ae0d8d2d42191b0b34c63c5eaf8b3812..0000000000000000000000000000000000000000 Binary files a/API/media/image69.emf and /dev/null differ diff --git a/API/media/image69.png b/API/media/image69.png deleted file mode 100644 index 46a0ec1eeb13926aa33cdac3600e4ca7d115e447..0000000000000000000000000000000000000000 Binary files a/API/media/image69.png and /dev/null differ diff --git a/API/media/image70.emf b/API/media/image70.emf deleted file mode 100644 index 8fb6fb0381741cf84b1958626421e22ed31bb4ed..0000000000000000000000000000000000000000 Binary files a/API/media/image70.emf and /dev/null differ diff --git a/API/media/image70.png b/API/media/image70.png deleted file mode 100644 index 46a0ec1eeb13926aa33cdac3600e4ca7d115e447..0000000000000000000000000000000000000000 Binary files a/API/media/image70.png and /dev/null differ diff --git a/API/media/image71.png b/API/media/image71.png deleted file mode 100644 index c4a8aa5b4dde56a6af180a5e32a3e1c6e992abe1..0000000000000000000000000000000000000000 Binary files a/API/media/image71.png and /dev/null differ diff --git a/API/media/image72.emf b/API/media/image72.emf deleted file mode 100644 index 137cc2d9c48c5f2b0a5c13d179b2eb922d083e75..0000000000000000000000000000000000000000 Binary files a/API/media/image72.emf and /dev/null differ diff --git a/API/media/image72.png b/API/media/image72.png deleted file mode 100644 index 46a0ec1eeb13926aa33cdac3600e4ca7d115e447..0000000000000000000000000000000000000000 Binary files a/API/media/image72.png and /dev/null differ diff --git a/API/media/image73.emf b/API/media/image73.emf deleted file mode 100644 index f93f7bd5740662326824ccb114868bf6df2c44d3..0000000000000000000000000000000000000000 Binary files a/API/media/image73.emf and /dev/null differ diff --git a/API/media/image73.png b/API/media/image73.png deleted file mode 100644 index bdd8d710a807a4562937719b2aca570319e56855..0000000000000000000000000000000000000000 Binary files a/API/media/image73.png and /dev/null differ diff --git a/API/media/image74.emf b/API/media/image74.emf deleted file mode 100644 index b3af144dd2c22ab06b8be7a91fd8bc50e005477b..0000000000000000000000000000000000000000 Binary files a/API/media/image74.emf and /dev/null differ diff --git a/API/media/image74.png b/API/media/image74.png deleted file mode 100644 index bdd8d710a807a4562937719b2aca570319e56855..0000000000000000000000000000000000000000 Binary files a/API/media/image74.png and /dev/null differ diff --git a/API/media/image75.emf b/API/media/image75.emf deleted file mode 100644 index 833a22a251992f03b6c61e2b0a3bfb52da69d728..0000000000000000000000000000000000000000 Binary files a/API/media/image75.emf and /dev/null differ diff --git a/API/media/image75.png b/API/media/image75.png deleted file mode 100644 index 15ea88bab5d0ca2abe5b7cc548cb100353cd999c..0000000000000000000000000000000000000000 Binary files a/API/media/image75.png and /dev/null differ diff --git a/API/media/image76.emf b/API/media/image76.emf deleted file mode 100644 index da3f3d6eb753dae60bdc04d9e02583ee625a3d56..0000000000000000000000000000000000000000 Binary files a/API/media/image76.emf and /dev/null differ diff --git a/API/media/image76.png b/API/media/image76.png deleted file mode 100644 index d8481fb62624decf9eac1ea1479ea3ca8c178933..0000000000000000000000000000000000000000 Binary files a/API/media/image76.png and /dev/null differ diff --git a/API/media/image77.emf b/API/media/image77.emf deleted file mode 100644 index 327ab2989ad75e51b27b8355b551824b9b724444..0000000000000000000000000000000000000000 Binary files a/API/media/image77.emf and /dev/null differ diff --git a/API/media/image77.png b/API/media/image77.png deleted file mode 100644 index d8481fb62624decf9eac1ea1479ea3ca8c178933..0000000000000000000000000000000000000000 Binary files a/API/media/image77.png and /dev/null differ diff --git a/API/media/image78.emf b/API/media/image78.emf deleted file mode 100644 index ed8789a4d03c83d3019308929c7fcf7a75b012df..0000000000000000000000000000000000000000 Binary files a/API/media/image78.emf and /dev/null differ diff --git a/API/media/image78.png b/API/media/image78.png deleted file mode 100644 index d8481fb62624decf9eac1ea1479ea3ca8c178933..0000000000000000000000000000000000000000 Binary files a/API/media/image78.png and /dev/null differ diff --git a/API/media/image79.png b/API/media/image79.png deleted file mode 100644 index 826540c43b84093c333c1a04592165e3086b8634..0000000000000000000000000000000000000000 Binary files a/API/media/image79.png and /dev/null differ diff --git a/API/media/image80.emf b/API/media/image80.emf deleted file mode 100644 index 04c9d956dfb87e1c9d9ad96047c92cd73a76e708..0000000000000000000000000000000000000000 Binary files a/API/media/image80.emf and /dev/null differ diff --git a/API/media/image80.png b/API/media/image80.png deleted file mode 100644 index d8481fb62624decf9eac1ea1479ea3ca8c178933..0000000000000000000000000000000000000000 Binary files a/API/media/image80.png and /dev/null differ diff --git a/API/media/image81.emf b/API/media/image81.emf deleted file mode 100644 index b4d45a7c48cf73a502b3db8472a719284c721035..0000000000000000000000000000000000000000 Binary files a/API/media/image81.emf and /dev/null differ diff --git a/API/media/image81.png b/API/media/image81.png deleted file mode 100644 index 30e0f3e980e18175b2feb1de3a6e8f756a028584..0000000000000000000000000000000000000000 Binary files a/API/media/image81.png and /dev/null differ diff --git a/API/media/image82.emf b/API/media/image82.emf deleted file mode 100644 index 23f0a5e7f4a15d48ad55b012c794e982aea6f351..0000000000000000000000000000000000000000 Binary files a/API/media/image82.emf and /dev/null differ diff --git a/API/media/image82.png b/API/media/image82.png deleted file mode 100644 index 30e0f3e980e18175b2feb1de3a6e8f756a028584..0000000000000000000000000000000000000000 Binary files a/API/media/image82.png and /dev/null differ diff --git a/API/media/image83.emf b/API/media/image83.emf deleted file mode 100644 index c3cb09edc6a92dc0e2a4922934bd277109eaff24..0000000000000000000000000000000000000000 Binary files a/API/media/image83.emf and /dev/null differ diff --git a/API/media/image83.png b/API/media/image83.png deleted file mode 100644 index 30e0f3e980e18175b2feb1de3a6e8f756a028584..0000000000000000000000000000000000000000 Binary files a/API/media/image83.png and /dev/null differ diff --git a/API/media/image84.png b/API/media/image84.png deleted file mode 100644 index f7c7be430fa5ec46f5044de22c702aca25978b88..0000000000000000000000000000000000000000 Binary files a/API/media/image84.png and /dev/null differ diff --git a/API/media/image85.png b/API/media/image85.png deleted file mode 100644 index 54ebe04a99ede549464103707fbde49a4082ebb1..0000000000000000000000000000000000000000 Binary files a/API/media/image85.png and /dev/null differ diff --git a/API/media/image86.png b/API/media/image86.png deleted file mode 100644 index d3cd1cae08ff330ee9db00ec7b884d3d9d9ccafe..0000000000000000000000000000000000000000 Binary files a/API/media/image86.png and /dev/null differ diff --git a/API/media/image87.png b/API/media/image87.png deleted file mode 100644 index 25dc86ea6a880e5594971f3403f755206acb4ab1..0000000000000000000000000000000000000000 Binary files a/API/media/image87.png and /dev/null differ diff --git a/API/media/image88.png b/API/media/image88.png deleted file mode 100644 index e66d0dde40501304f4803342ae98890857978f7c..0000000000000000000000000000000000000000 Binary files a/API/media/image88.png and /dev/null differ diff --git a/API/media/image89.png b/API/media/image89.png deleted file mode 100644 index 41d71d8b1d5a3ff5ad248b9bf61075c1799c4660..0000000000000000000000000000000000000000 Binary files a/API/media/image89.png and /dev/null differ diff --git a/API/media/image90.png b/API/media/image90.png deleted file mode 100644 index e8e5a3db1ae59b4d152d6ef887497cb67a75687b..0000000000000000000000000000000000000000 Binary files a/API/media/image90.png and /dev/null differ diff --git a/API/media/image91.png b/API/media/image91.png deleted file mode 100644 index 4900ed31bfc22e7917fea9dcf10f571b1067349f..0000000000000000000000000000000000000000 Binary files a/API/media/image91.png and /dev/null differ diff --git a/API/media/image92.png b/API/media/image92.png deleted file mode 100644 index c60831572e1ccd0f3c3c7808812eb94a44525fa8..0000000000000000000000000000000000000000 Binary files a/API/media/image92.png and /dev/null differ diff --git a/API/media/image93.png b/API/media/image93.png deleted file mode 100644 index ad659c4f2a06252eafbfa04e4abeff4ce7e73dc5..0000000000000000000000000000000000000000 Binary files a/API/media/image93.png and /dev/null differ diff --git a/API/media/image94.png b/API/media/image94.png deleted file mode 100644 index 62e72bc8eefaa5c558896e290f0b649b8f9a4a6d..0000000000000000000000000000000000000000 Binary files a/API/media/image94.png and /dev/null differ diff --git a/API/media/image95.png b/API/media/image95.png deleted file mode 100644 index 47b822035228c0ba6ec4dda15d54e5a58365e727..0000000000000000000000000000000000000000 Binary files a/API/media/image95.png and /dev/null differ diff --git a/API/media/image96.png b/API/media/image96.png deleted file mode 100644 index 692712e192fc925976a4d9683bfa2f5d9dfd05ed..0000000000000000000000000000000000000000 Binary files a/API/media/image96.png and /dev/null differ diff --git a/API/media/image97.png b/API/media/image97.png deleted file mode 100644 index 5a7c0fd32fd4d8e5f33b816f9b9cd2a1bb8d91eb..0000000000000000000000000000000000000000 Binary files a/API/media/image97.png and /dev/null differ diff --git a/API/media/image98.png b/API/media/image98.png deleted file mode 100644 index 3f607e5c44b567d1d5bb24b0c010c613e79d08b2..0000000000000000000000000000000000000000 Binary files a/API/media/image98.png and /dev/null differ diff --git a/API/media/image99.png b/API/media/image99.png deleted file mode 100644 index 3aca893dc4525515fada8d83b53e5d7b89bf6217..0000000000000000000000000000000000000000 Binary files a/API/media/image99.png and /dev/null differ diff --git a/API/media/references.json b/API/media/references.json deleted file mode 100644 index 079c63da9d4afc9ef1e011ccb6c70f54a40c6c9f..0000000000000000000000000000000000000000 --- a/API/media/references.json +++ /dev/null @@ -1 +0,0 @@ -{"1":"#1","10":"#10","11":"#11","12":"#12","13":"#13","14":"#14","15":"#15","16":"#16","17":"#17","18":"#18","19":"#19","2":"#2","20":"#20","21":"#21","22":"#22","23":"#23","24":"#24","25":"#25","26":"#26","27":"#27","28":"#28","29":"#29","3":"#3","30":"#30","31":"#31","32":"#32","33":"#33","34":"#34","35":"#35","36":"#36","37":"#37","4":"#4","5":"#5","6":"#6","7":"#7","8":"#8","9":"#9","i.1":"#i.1","i.10":"#i.10","i.11":"#i.11","i.12":"#i.12","i.13":"#i.13","i.14":"#i.14","i.15":"#i.15","i.16":"#i.16","i.17":"#i.17","i.18":"#i.18","i.19":"#i.19","i.2":"#i.2","i.20":"#i.20","i.21":"#i.21","i.22":"#i.22","i.3":"#i.3","i.4":"#i.4","i.5":"#i.5","i.6":"#i.6","i.7":"#i.7","i.8":"#i.8","i.9":"#i.9"} \ No newline at end of file diff --git a/API/media/toc.json b/API/media/toc.json deleted file mode 100644 index e93aaadc46a9fb22b262d4ed5a89724375c96b84..0000000000000000000000000000000000000000 --- a/API/media/toc.json +++ /dev/null @@ -1 +0,0 @@ -{"c":[[{"c":[{"c":[["toc-intellectual-property-rights",[],[]],[{"c":"Intellectual","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"},{"t":"Space"},{"c":"Rights","t":"Str"}],["#intellectual-property-rights",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-foreword",[],[]],[{"c":"Foreword","t":"Str"}],["#foreword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-modal-verbs-terminology",[],[]],[{"c":"Modal","t":"Str"},{"t":"Space"},{"c":"verbs","t":"Str"},{"t":"Space"},{"c":"terminology","t":"Str"}],["#modal-verbs-terminology",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-executive-summary",[],[]],[{"c":"Executive","t":"Str"},{"t":"Space"},{"c":"summary","t":"Str"}],["#executive-summary",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-introduction",[],[]],[{"c":"Introduction","t":"Str"}],["#introduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabscope",[],[]],[{"c":"1\tScope","t":"Str"}],["#tabscope",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabreferences",[],[]],[{"c":"2\tReferences","t":"Str"}],["#tabreferences",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabnormative-references",[],[]],[{"c":"2.1\tNormative","t":"Str"},{"t":"Space"},{"c":"references","t":"Str"}],["#tabnormative-references",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinformative-references",[],[]],[{"c":"2.2\tInformative","t":"Str"},{"t":"Space"},{"c":"references","t":"Str"}],["#tabinformative-references",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdefinition-of-terms-symbols-and-abbreviations",[],[]],[{"c":"3\tDefinition","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"terms,","t":"Str"},{"t":"Space"},{"c":"symbols","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"abbreviations","t":"Str"}],["#tabdefinition-of-terms-symbols-and-abbreviations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabterms",[],[]],[{"c":"3.1\tTerms","t":"Str"}],["#tabterms",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsymbols",[],[]],[{"c":"3.2\tSymbols","t":"Str"}],["#tabsymbols",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tababbreviations",[],[]],[{"c":"3.3\tAbbreviations","t":"Str"}],["#tababbreviations",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-information-management-framework",[],[]],[{"c":"4\tContext","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Management","t":"Str"},{"t":"Space"},{"c":"Framework","t":"Str"}],["#tabcontext-information-management-framework",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction",[],[]],[{"c":"4.1\tIntroduction","t":"Str"}],["#tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-information-model",[],[]],[{"c":"4.2\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Model","t":"Str"}],["#tabngsi-ld-information-model",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-1",[],[]],[{"c":"4.2.1\tIntroduction","t":"Str"}],["#tabintroduction-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-meta-model",[],[]],[{"c":"4.2.2\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Meta","t":"Str"},{"t":"Space"},{"c":"Model","t":"Str"}],["#tabngsi-ld-meta-model",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcross-domain-ontology",[],[]],[{"c":"4.2.3\tCross","t":"Str"},{"t":"Space"},{"c":"Domain","t":"Str"},{"t":"Space"},{"c":"Ontology","t":"Str"}],["#tabcross-domain-ontology",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-domain-specific-models-and-instantiation",[],[]],[{"c":"4.2.4\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"domain-specific","t":"Str"},{"t":"Space"},{"c":"models","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"instantiation","t":"Str"}],["#tabngsi-ld-domain-specific-models-and-instantiation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuml-representation",[],[]],[{"c":"4.2.5\tUML","t":"Str"},{"t":"Space"},{"c":"representation","t":"Str"}],["#tabuml-representation",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-architectural-considerations",[],[]],[{"c":"4.3\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Architectural","t":"Str"},{"t":"Space"},{"c":"Considerations","t":"Str"}],["#tabngsi-ld-architectural-considerations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-2",[],[]],[{"c":"4.3.1\tIntroduction","t":"Str"}],["#tabintroduction-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcentralized-architecture",[],[]],[{"c":"4.3.2\tCentralized","t":"Str"},{"t":"Space"},{"c":"architecture","t":"Str"}],["#tabcentralized-architecture",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdistributed-architecture",[],[]],[{"c":"4.3.3\tDistributed","t":"Str"},{"t":"Space"},{"c":"architecture","t":"Str"}],["#tabdistributed-architecture",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabfederated-architecture",[],[]],[{"c":"4.3.4\tFederated","t":"Str"},{"t":"Space"},{"c":"architecture","t":"Str"}],["#tabfederated-architecture",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-api-structure-and-implementation-options",[],[]],[{"c":"4.3.5\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"API","t":"Str"},{"t":"Space"},{"c":"Structure","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Implementation","t":"Str"},{"t":"Space"},{"c":"Options","t":"Str"}],["#tabngsi-ld-api-structure-and-implementation-options",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdistributed-operations",[],[]],[{"c":"4.3.6\tDistributed","t":"Str"},{"t":"Space"},{"c":"Operations","t":"Str"}],["#tabdistributed-operations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-3",[],[]],[{"c":"4.3.6.1\tIntroduction","t":"Str"}],["#tabintroduction-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabadditive-registrations",[],[]],[{"c":"4.3.6.2\tAdditive","t":"Str"},{"t":"Space"},{"c":"Registrations","t":"Str"}],["#tabadditive-registrations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabproxied-registrations",[],[]],[{"c":"4.3.6.3\tProxied","t":"Str"},{"t":"Space"},{"c":"Registrations","t":"Str"}],["#tabproxied-registrations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablimiting-cascading-distributed-operations",[],[]],[{"c":"4.3.6.4\tLimiting","t":"Str"},{"t":"Space"},{"c":"Cascading","t":"Str"},{"t":"Space"},{"c":"Distributed","t":"Str"},{"t":"Space"},{"c":"Operations","t":"Str"}],["#tablimiting-cascading-distributed-operations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabextra-information-to-provide-when-contacting-context-source",[],[]],[{"c":"4.3.6.5\tExtra","t":"Str"},{"t":"Space"},{"c":"information","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"provide","t":"Str"},{"t":"Space"},{"c":"when","t":"Str"},{"t":"Space"},{"c":"contacting","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"}],["#tabextra-information-to-provide-when-contacting-context-source",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source",[],[]],[{"c":"4.3.6.6\tAdditional","t":"Str"},{"t":"Space"},{"c":"pre-","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"post-processing","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"extra","t":"Str"},{"t":"Space"},{"c":"information","t":"Str"},{"t":"Space"},{"c":"when","t":"Str"},{"t":"Space"},{"c":"contacting","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"}],["#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabquerying-and-retrieving-distributed-entities-as-unitary-operations",[],[]],[{"c":"4.3.6.7\tQuerying","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Retrieving","t":"Str"},{"t":"Space"},{"c":"Distributed","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"},{"t":"Space"},{"c":"as","t":"Str"},{"t":"Space"},{"c":"Unitary","t":"Str"},{"t":"Space"},{"c":"Operations","t":"Str"}],["#tabquerying-and-retrieving-distributed-entities-as-unitary-operations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbackwards-compatibility-of-context-source-payloads",[],[]],[{"c":"4.3.6.8\tBackwards","t":"Str"},{"t":"Space"},{"c":"compatibility","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"payloads","t":"Str"}],["#tabbackwards-compatibility-of-context-source-payloads",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabsnapshots",[],[]],[{"c":"4.3.7\tSnapshots","t":"Str"}],["#tabsnapshots",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcore-and-user-ngsi-ld-context",[],[]],[{"c":"4.4\tCore","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"user","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"}],["#tabcore-and-user-ngsi-ld-context",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-data-representation",[],[]],[{"c":"4.5\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Data","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabngsi-ld-data-representation",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-4",[],[]],[{"c":"4.5.0\tIntroduction","t":"Str"}],["#tabintroduction-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-entity-representation",[],[]],[{"c":"4.5.1\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabngsi-ld-entity-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-property-representations",[],[]],[{"c":"4.5.2\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-property-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-5",[],[]],[{"c":"4.5.2.1\tIntroduction","t":"Str"}],["#tabintroduction-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-property",[],[]],[{"c":"4.5.2.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"}],["#tabnormalized-ngsi-ld-property",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-property",[],[]],[{"c":"4.5.2.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"}],["#tabconcise-ngsi-ld-property",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-relationship-representations",[],[]],[{"c":"4.5.3\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Relationship","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-relationship-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-6",[],[]],[{"c":"4.5.3.1\tIntroduction","t":"Str"}],["#tabintroduction-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-relationship",[],[]],[{"c":"4.5.3.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Relationship","t":"Str"}],["#tabnormalized-ngsi-ld-relationship",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-relationship",[],[]],[{"c":"4.5.3.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Relationship","t":"Str"}],["#tabconcise-ngsi-ld-relationship",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabsimplified-representation",[],[]],[{"c":"4.5.4\tSimplified","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabsimplified-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabmulti-attribute-support",[],[]],[{"c":"4.5.5\tMulti-Attribute","t":"Str"},{"t":"Space"},{"c":"Support","t":"Str"}],["#tabmulti-attribute-support",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-7",[],[]],[{"c":"4.5.5.1\tIntroduction","t":"Str"}],["#tabintroduction-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabprocessing-of-conflicting-transient-entities",[],[]],[{"c":"4.5.5.2\tProcessing","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Conflicting","t":"Str"},{"t":"Space"},{"c":"Transient","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabprocessing-of-conflicting-transient-entities",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabprocessing-of-conflicting-attributes",[],[]],[{"c":"4.5.5.3\tProcessing","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Conflicting","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabprocessing-of-conflicting-attributes",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabtemporal-representation-of-an-entity",[],[]],[{"c":"4.5.6\tTemporal","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabtemporal-representation-of-an-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtemporal-representation-of-a-property",[],[]],[{"c":"4.5.7\tTemporal","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"}],["#tabtemporal-representation-of-a-property",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtemporal-representation-of-a-relationship",[],[]],[{"c":"4.5.8\tTemporal","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Relationship","t":"Str"}],["#tabtemporal-representation-of-a-relationship",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsimplified-temporal-representation-of-an-entity",[],[]],[{"c":"4.5.9\tSimplified","t":"Str"},{"t":"Space"},{"c":"temporal","t":"Str"},{"t":"Space"},{"c":"representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabsimplified-temporal-representation-of-an-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentity-type-list-representation",[],[]],[{"c":"4.5.10\tEntity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"List","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabentity-type-list-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdetailed-entity-type-list-representation",[],[]],[{"c":"4.5.11\tDetailed","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"List","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabdetailed-entity-type-list-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentity-type-information-representation",[],[]],[{"c":"4.5.12\tEntity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabentity-type-information-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabattribute-list-representation",[],[]],[{"c":"4.5.13\tAttribute","t":"Str"},{"t":"Space"},{"c":"List","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabattribute-list-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdetailed-attribute-list-representation",[],[]],[{"c":"4.5.14\tDetailed","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"List","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabdetailed-attribute-list-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabattribute-information-representation",[],[]],[{"c":"4.5.15\tAttribute","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabattribute-information-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeojson-representation-of-entities",[],[]],[{"c":"4.5.16\tGeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabgeojson-representation-of-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabforeword",[],[]],[{"c":"4.5.16.0\tForeword","t":"Str"}],["#tabforeword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtop-level-geometry-field-selection-algorithm",[],[]],[{"c":"4.5.16.1\tTop-level","t":"Str"},{"t":"Space"},{"c":"\"geometry\"","t":"Str"},{"t":"Space"},{"c":"field","t":"Str"},{"t":"Space"},{"c":"selection","t":"Str"},{"t":"Space"},{"c":"algorithm","t":"Str"}],["#tabtop-level-geometry-field-selection-algorithm",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeojson-representation-of-an-individual-entity",[],[]],[{"c":"4.5.16.2\tGeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"individual","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabgeojson-representation-of-an-individual-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeojson-representation-of-multiple-entities",[],[]],[{"c":"4.5.16.3\tGeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Multiple","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabgeojson-representation-of-multiple-entities",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabsimplified-geojson-representation-of-entities",[],[]],[{"c":"4.5.17\tSimplified","t":"Str"},{"t":"Space"},{"c":"GeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabsimplified-geojson-representation-of-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabforeword-1",[],[]],[{"c":"4.5.17.0\tForeword","t":"Str"}],["#tabforeword-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsimplified-geojson-representation-of-an-individual-entity",[],[]],[{"c":"4.5.17.1\tSimplified","t":"Str"},{"t":"Space"},{"c":"GeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"individual","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabsimplified-geojson-representation-of-an-individual-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsimplified-geojson-representation-of-multiple-entities",[],[]],[{"c":"4.5.17.2\tSimplified","t":"Str"},{"t":"Space"},{"c":"GeoJSON","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"multiple","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabsimplified-geojson-representation-of-multiple-entities",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-languageproperty-representations",[],[]],[{"c":"4.5.18\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"LanguageProperty","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-languageproperty-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-8",[],[]],[{"c":"4.5.18.1\tIntroduction","t":"Str"}],["#tabintroduction-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-languageproperty",[],[]],[{"c":"4.5.18.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"LanguageProperty","t":"Str"}],["#tabnormalized-ngsi-ld-languageproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-languageproperty",[],[]],[{"c":"4.5.18.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"LanguageProperty","t":"Str"}],["#tabconcise-ngsi-ld-languageproperty",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabaggregated-temporal-representation-of-an-entity",[],[]],[{"c":"4.5.19\tAggregated","t":"Str"},{"t":"Space"},{"c":"temporal","t":"Str"},{"t":"Space"},{"c":"representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabaggregated-temporal-representation-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabforeword-2",[],[]],[{"c":"4.5.19.0\tForeword","t":"Str"}],["#tabforeword-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupported-behaviours-for-aggregation-functions",[],[]],[{"c":"4.5.19.1\tSupported","t":"Str"},{"t":"Space"},{"c":"behaviours","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"aggregation","t":"Str"},{"t":"Space"},{"c":"functions","t":"Str"}],["#tabsupported-behaviours-for-aggregation-functions",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-vocabproperty-representations",[],[]],[{"c":"4.5.20\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"VocabProperty","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-vocabproperty-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-9",[],[]],[{"c":"4.5.20.1\tIntroduction","t":"Str"}],["#tabintroduction-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-vocabproperty",[],[]],[{"c":"4.5.20.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"VocabProperty","t":"Str"}],["#tabnormalized-ngsi-ld-vocabproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-vocabproperty",[],[]],[{"c":"4.5.20.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"VocabProperty","t":"Str"}],["#tabconcise-ngsi-ld-vocabproperty",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-listproperty-representations",[],[]],[{"c":"4.5.21\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListProperty","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-listproperty-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-10",[],[]],[{"c":"4.5.21.1\tIntroduction","t":"Str"}],["#tabintroduction-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-listproperty",[],[]],[{"c":"4.5.21.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListProperty","t":"Str"}],["#tabnormalized-ngsi-ld-listproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-listproperty",[],[]],[{"c":"4.5.21.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListProperty","t":"Str"}],["#tabconcise-ngsi-ld-listproperty",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-listrelationship-representations",[],[]],[{"c":"4.5.22\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListRelationship","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-listrelationship-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-11",[],[]],[{"c":"4.5.22.1\tIntroduction","t":"Str"}],["#tabintroduction-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-listrelationship",[],[]],[{"c":"4.5.22.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListRelationship","t":"Str"}],["#tabnormalized-ngsi-ld-listrelationship",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-listrelationship",[],[]],[{"c":"4.5.22.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"ListRelationship","t":"Str"}],["#tabconcise-ngsi-ld-listrelationship",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-linked-entity-retrieval",[],[]],[{"c":"4.5.23\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Linked","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Retrieval","t":"Str"}],["#tabngsi-ld-linked-entity-retrieval",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-12",[],[]],[{"c":"4.5.23.1\tIntroduction","t":"Str"}],["#tabintroduction-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinline-linked-entity-representation",[],[]],[{"c":"4.5.23.2\tInline","t":"Str"},{"t":"Space"},{"c":"Linked","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabinline-linked-entity-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabflattened-linked-entity-representation",[],[]],[{"c":"4.5.23.3\tFlattened","t":"Str"},{"t":"Space"},{"c":"Linked","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabflattened-linked-entity-representation",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-jsonproperty-representations",[],[]],[{"c":"4.5.24\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"JsonProperty","t":"Str"},{"t":"Space"},{"c":"Representations","t":"Str"}],["#tabngsi-ld-jsonproperty-representations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-13",[],[]],[{"c":"4.5.24.1\tIntroduction","t":"Str"}],["#tabintroduction-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnormalized-ngsi-ld-jsonproperty",[],[]],[{"c":"4.5.24.2\tNormalized","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"JsonProperty","t":"Str"}],["#tabnormalized-ngsi-ld-jsonproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-jsonproperty",[],[]],[{"c":"4.5.24.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"JsonProperty","t":"Str"}],["#tabconcise-ngsi-ld-jsonproperty",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-entitymap-representation",[],[]],[{"c":"4.5.25\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#tabngsi-ld-entitymap-representation",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdata-representation-restrictions",[],[]],[{"c":"4.6\tData","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"},{"t":"Space"},{"c":"Restrictions","t":"Str"}],["#tabdata-representation-restrictions",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabsupported-text-encodings",[],[]],[{"c":"4.6.1\tSupported","t":"Str"},{"t":"Space"},{"c":"text","t":"Str"},{"t":"Space"},{"c":"encodings","t":"Str"}],["#tabsupported-text-encodings",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupported-names",[],[]],[{"c":"4.6.2\tSupported","t":"Str"},{"t":"Space"},{"c":"names","t":"Str"}],["#tabsupported-names",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupported-data-types-for-values",[],[]],[{"c":"4.6.3\tSupported","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"},{"t":"Space"},{"c":"types","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"Values","t":"Str"}],["#tabsupported-data-types-for-values",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupported-content",[],[]],[{"c":"4.6.4\tSupported","t":"Str"},{"t":"Space"},{"c":"Content","t":"Str"}],["#tabsupported-content",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupported-data-types-for-languagemaps",[],[]],[{"c":"4.6.5\tSupported","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"},{"t":"Space"},{"c":"types","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"LanguageMaps","t":"Str"}],["#tabsupported-data-types-for-languagemaps",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity",[],[]],[{"c":"4.6.6\tOrdering","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"},{"t":"Space"},{"c":"in","t":"Str"},{"t":"Space"},{"c":"arrays","t":"Str"},{"t":"Space"},{"c":"having","t":"Str"},{"t":"Space"},{"c":"more","t":"Str"},{"t":"Space"},{"c":"than","t":"Str"},{"t":"Space"},{"c":"one","t":"Str"},{"t":"Space"},{"c":"instance","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"same","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabgeospatial-properties",[],[]],[{"c":"4.7\tGeospatial","t":"Str"},{"t":"Space"},{"c":"Properties","t":"Str"}],["#tabgeospatial-properties",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabgeojson-geometries",[],[]],[{"c":"4.7.1\tGeoJSON","t":"Str"},{"t":"Space"},{"c":"Geometries","t":"Str"}],["#tabgeojson-geometries",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabrepresentation-of-geojson-geometries-in-json-ld",[],[]],[{"c":"4.7.2\tRepresentation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"GeoJSON","t":"Str"},{"t":"Space"},{"c":"Geometries","t":"Str"},{"t":"Space"},{"c":"in","t":"Str"},{"t":"Space"},{"c":"JSON-LD","t":"Str"}],["#tabrepresentation-of-geojson-geometries-in-json-ld",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabconcise-ngsi-ld-geoproperty",[],[]],[{"c":"4.7.3\tConcise","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"GeoProperty","t":"Str"}],["#tabconcise-ngsi-ld-geoproperty",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabtemporal-properties",[],[]],[{"c":"4.8\tTemporal","t":"Str"},{"t":"Space"},{"c":"Properties","t":"Str"}],["#tabtemporal-properties",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-query-language",[],[]],[{"c":"4.9\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-query-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-geoquery-language",[],[]],[{"c":"4.10\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Geoquery","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-geoquery-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-temporal-query-language",[],[]],[{"c":"4.11\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-temporal-query-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-pagination",[],[]],[{"c":"4.12\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Pagination","t":"Str"}],["#tabngsi-ld-pagination",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcounting-the-number-of-results",[],[]],[{"c":"4.13\tCounting","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"Number","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Results","t":"Str"}],["#tabcounting-the-number-of-results",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupporting-multiple-tenants",[],[]],[{"c":"4.14\tSupporting","t":"Str"},{"t":"Space"},{"c":"Multiple","t":"Str"},{"t":"Space"},{"c":"Tenants","t":"Str"}],["#tabsupporting-multiple-tenants",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-language-filter",[],[]],[{"c":"4.15\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"},{"t":"Space"},{"c":"Filter","t":"Str"}],["#tabngsi-ld-language-filter",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsupporting-multiple-entity-types",[],[]],[{"c":"4.16\tSupporting","t":"Str"},{"t":"Space"},{"c":"Multiple","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#tabsupporting-multiple-entity-types",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-entity-type-selection-language",[],[]],[{"c":"4.17\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"Selection","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-entity-type-selection-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-scopes",[],[]],[{"c":"4.18\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Scopes","t":"Str"}],["#tabngsi-ld-scopes",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-scope-query-language",[],[]],[{"c":"4.19\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Scope","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-scope-query-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-distributed-operation-names",[],[]],[{"c":"4.20\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Distributed","t":"Str"},{"t":"Space"},{"c":"Operation","t":"Str"},{"t":"Space"},{"c":"names","t":"Str"}],["#tabngsi-ld-distributed-operation-names",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-attribute-projection-language",[],[]],[{"c":"4.21\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"Projection","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-attribute-projection-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtransient-storage-of-entities-and-attributes",[],[]],[{"c":"4.22\tTransient","t":"Str"},{"t":"Space"},{"c":"Storage","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabtransient-storage-of-entities-and-attributes",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentity-ordering",[],[]],[{"c":"4.23\tEntity","t":"Str"},{"t":"Space"},{"c":"Ordering","t":"Str"},{"t":"Space"}],["#tabentity-ordering",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-14",[],[]],[{"c":"4.23.1\tIntroduction","t":"Str"}],["#tabintroduction-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdatatype-comparison-order",[],[]],[{"c":"4.23.2\tDatatype","t":"Str"},{"t":"Space"},{"c":"Comparison","t":"Str"},{"t":"Space"},{"c":"Order","t":"Str"}],["#tabdatatype-comparison-order",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabngsi-ld-entity-ordering-language",[],[]],[{"c":"4.23.3\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Ordering","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#tabngsi-ld-entity-ordering-language",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabapi-operation-definition",[],[]],[{"c":"5\tAPI","t":"Str"},{"t":"Space"},{"c":"Operation","t":"Str"},{"t":"Space"},{"c":"Definition","t":"Str"}],["#tabapi-operation-definition",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-15",[],[]],[{"c":"5.1\tIntroduction","t":"Str"}],["#tabintroduction-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdata-types",[],[]],[{"c":"5.2\tData","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#tabdata-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-16",[],[]],[{"c":"5.2.1\tIntroduction","t":"Str"}],["#tabintroduction-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcommon-members",[],[]],[{"c":"5.2.2\tCommon","t":"Str"},{"t":"Space"},{"c":"members","t":"Str"}],["#tabcommon-members",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcontext",[],[]],[{"c":"5.2.3\t@context","t":"Str"}],["#tabcontext",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentity",[],[]],[{"c":"5.2.4\tEntity","t":"Str"}],["#tabentity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabproperty",[],[]],[{"c":"5.2.5\tProperty","t":"Str"}],["#tabproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabrelationship",[],[]],[{"c":"5.2.6\tRelationship","t":"Str"}],["#tabrelationship",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeoproperty",[],[]],[{"c":"5.2.7\tGeoProperty","t":"Str"}],["#tabgeoproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentityinfo",[],[]],[{"c":"5.2.8\tEntityInfo","t":"Str"}],["#tabentityinfo",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcsourceregistration",[],[]],[{"c":"5.2.9\tCSourceRegistration","t":"Str"}],["#tabcsourceregistration",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabregistrationinfo",[],[]],[{"c":"5.2.10\tRegistrationInfo","t":"Str"}],["#tabregistrationinfo",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtimeinterval",[],[]],[{"c":"5.2.11\tTimeInterval","t":"Str"}],["#tabtimeinterval",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsubscription",[],[]],[{"c":"5.2.12\tSubscription","t":"Str"}],["#tabsubscription",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeoquery",[],[]],[{"c":"5.2.13\tGeoQuery","t":"Str"}],["#tabgeoquery",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnotificationparams",[],[]],[{"c":"5.2.14\tNotificationParams","t":"Str"}],["#tabnotificationparams",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabnotificationparams-data-type-definition",[],[]],[{"c":"5.2.14.1\tNotificationParams","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"},{"t":"Space"},{"c":"type","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabnotificationparams-data-type-definition",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-only-members",[],[]],[{"c":"5.2.14.2\tOutput","t":"Str"},{"t":"Space"},{"c":"only","t":"Str"},{"t":"Space"},{"c":"members","t":"Str"}],["#taboutput-only-members",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabendpoint",[],[]],[{"c":"5.2.15\tEndpoint","t":"Str"}],["#tabendpoint",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatchoperationresult",[],[]],[{"c":"5.2.16\tBatchOperationResult","t":"Str"}],["#tabbatchoperationresult",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatchentityerror",[],[]],[{"c":"5.2.17\tBatchEntityError","t":"Str"}],["#tabbatchentityerror",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabupdateresult",[],[]],[{"c":"5.2.18\tUpdateResult","t":"Str"}],["#tabupdateresult",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnotupdateddetails",[],[]],[{"c":"5.2.19\tNotUpdatedDetails","t":"Str"}],["#tabnotupdateddetails",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentitytemporal",[],[]],[{"c":"5.2.20\tEntityTemporal","t":"Str"}],["#tabentitytemporal",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtemporalquery",[],[]],[{"c":"5.2.21\tTemporalQuery","t":"Str"}],["#tabtemporalquery",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabkeyvaluepair",[],[]],[{"c":"5.2.22\tKeyValuePair","t":"Str"}],["#tabkeyvaluepair",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabquery",[],[]],[{"c":"5.2.23\tQuery","t":"Str"}],["#tabquery",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentitytypelist",[],[]],[{"c":"5.2.24\tEntityTypeList","t":"Str"}],["#tabentitytypelist",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentitytype",[],[]],[{"c":"5.2.25\tEntityType","t":"Str"}],["#tabentitytype",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentitytypeinfo",[],[]],[{"c":"5.2.26\tEntityTypeInfo","t":"Str"}],["#tabentitytypeinfo",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabattributelist",[],[]],[{"c":"5.2.27\tAttributeList","t":"Str"}],["#tabattributelist",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabattribute",[],[]],[{"c":"5.2.28\tAttribute","t":"Str"}],["#tabattribute",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabfeature",[],[]],[{"c":"5.2.29\tFeature","t":"Str"}],["#tabfeature",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabfeaturecollection",[],[]],[{"c":"5.2.30\tFeatureCollection","t":"Str"}],["#tabfeaturecollection",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabfeatureproperties",[],[]],[{"c":"5.2.31\tFeatureProperties","t":"Str"}],["#tabfeatureproperties",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablanguageproperty",[],[]],[{"c":"5.2.32\tLanguageProperty","t":"Str"}],["#tablanguageproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentityselector",[],[]],[{"c":"5.2.33\tEntitySelector","t":"Str"}],["#tabentityselector",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabregistrationmanagementinfo",[],[]],[{"c":"5.2.34\tRegistrationManagementInfo","t":"Str"}],["#tabregistrationmanagementinfo",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabvocabproperty",[],[]],[{"c":"5.2.35\tVocabProperty","t":"Str"}],["#tabvocabproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablistproperty",[],[]],[{"c":"5.2.36\tListProperty","t":"Str"}],["#tablistproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablistrelationship",[],[]],[{"c":"5.2.37\tListRelationship","t":"Str"}],["#tablistrelationship",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabjsonproperty",[],[]],[{"c":"5.2.38\tJsonProperty","t":"Str"}],["#tabjsonproperty",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabentitymap",[],[]],[{"c":"5.2.39\tEntityMap","t":"Str"}],["#tabentitymap",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcontext-source-identity",[],[]],[{"c":"5.2.40\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Identity","t":"Str"}],["#tabcontext-source-identity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsnapshot",[],[]],[{"c":"5.2.41\tSnapshot","t":"Str"}],["#tabsnapshot",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabexecutionresultdetails",[],[]],[{"c":"5.2.42\tExecutionResultDetails","t":"Str"}],["#tabexecutionresultdetails",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taborderingparams",[],[]],[{"c":"5.2.43\tOrderingParams","t":"Str"}],["#taborderingparams",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabaggregationparams",[],[]],[{"c":"5.2.44\tAggregationParams","t":"Str"}],["#tabaggregationparams",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabnotification-data-types",[],[]],[{"c":"5.3\tNotification","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"},{"t":"Space"},{"c":"types","t":"Str"}],["#tabnotification-data-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabnotification",[],[]],[{"c":"5.3.1\tNotification","t":"Str"}],["#tabnotification",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcsourcenotification",[],[]],[{"c":"5.3.2\tCSourceNotification","t":"Str"}],["#tabcsourcenotification",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtriggerreasonenumeration",[],[]],[{"c":"5.3.3\tTriggerReasonEnumeration","t":"Str"}],["#tabtriggerreasonenumeration",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsnapshotnotification",[],[]],[{"c":"5.3.4\tSnapshotNotification","t":"Str"}],["#tabsnapshotnotification",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabngsi-ld-fragments",[],[]],[{"c":"5.4\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"Fragments","t":"Str"}],["#tabngsi-ld-fragments",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcommon-behaviours",[],[]],[{"c":"5.5\tCommon","t":"Str"},{"t":"Space"},{"c":"Behaviours","t":"Str"}],["#tabcommon-behaviours",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-17",[],[]],[{"c":"5.5.1\tIntroduction","t":"Str"}],["#tabintroduction-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taberror-types",[],[]],[{"c":"5.5.2\tError","t":"Str"},{"t":"Space"},{"c":"types","t":"Str"}],["#taberror-types",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taberror-response-payload-body",[],[]],[{"c":"5.5.3\tError","t":"Str"},{"t":"Space"},{"c":"response","t":"Str"},{"t":"Space"},{"c":"payload","t":"Str"},{"t":"Space"},{"c":"body","t":"Str"}],["#taberror-response-payload-body",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeneral-ngsi-ld-validation",[],[]],[{"c":"5.5.4\tGeneral","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"validation","t":"Str"}],["#tabgeneral-ngsi-ld-validation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdefault-context-assignment",[],[]],[{"c":"5.5.5\tDefault","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"},{"t":"Space"},{"c":"assignment","t":"Str"}],["#tabdefault-context-assignment",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboperation-execution-and-generic-error-handling",[],[]],[{"c":"5.5.6\tOperation","t":"Str"},{"t":"Space"},{"c":"execution","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"generic","t":"Str"},{"t":"Space"},{"c":"error","t":"Str"},{"t":"Space"},{"c":"handling","t":"Str"}],["#taboperation-execution-and-generic-error-handling",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabterm-to-uri-expansion-or-compaction",[],[]],[{"c":"5.5.7\tTerm","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"URI","t":"Str"},{"t":"Space"},{"c":"expansion","t":"Str"},{"t":"Space"},{"c":"or","t":"Str"},{"t":"Space"},{"c":"compaction","t":"Str"}],["#tabterm-to-uri-expansion-or-compaction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpartial-update-patch-behaviour",[],[]],[{"c":"5.5.8\tPartial","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"},{"t":"Space"},{"c":"Patch","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabpartial-update-patch-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpagination-behaviour",[],[]],[{"c":"5.5.9\tPagination","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabpagination-behaviour",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabgeneral-pagination-behaviour",[],[]],[{"c":"5.5.9.1\tGeneral","t":"Str"},{"t":"Space"},{"c":"Pagination","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabgeneral-pagination-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpagination-option-using-limit-and-offset",[],[]],[{"c":"5.5.9.2\tPagination","t":"Str"},{"t":"Space"},{"c":"option","t":"Str"},{"t":"Space"},{"c":"using","t":"Str"},{"t":"Space"},{"c":"limit","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"offset","t":"Str"}],["#tabpagination-option-using-limit-and-offset",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpagination-with-entity-maps",[],[]],[{"c":"5.5.9.3\tPagination","t":"Str"},{"t":"Space"},{"c":"with","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"maps","t":"Str"}],["#tabpagination-with-entity-maps",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabmulti-tenant-behaviour",[],[]],[{"c":"5.5.10\tMulti-Tenant","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabmulti-tenant-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabmore-than-one-instance-of-the-same-entity-in-an-entity-array",[],[]],[{"c":"5.5.11\tMore","t":"Str"},{"t":"Space"},{"c":"than","t":"Str"},{"t":"Space"},{"c":"one","t":"Str"},{"t":"Space"},{"c":"instance","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"same","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"in","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"array","t":"Str"}],["#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabforeword-3",[],[]],[{"c":"5.5.11.0\tForeword","t":"Str"}],["#tabforeword-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatch-entity-creation-case",[],[]],[{"c":"5.5.11.1\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Creation","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"}],["#tabbatch-entity-creation-case",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatch-entity-creation-or-update-upsert-case",[],[]],[{"c":"5.5.11.2\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Creation","t":"Str"},{"t":"Space"},{"c":"or","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"},{"t":"Space"},{"c":"(Upsert)","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"}],["#tabbatch-entity-creation-or-update-upsert-case",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatch-entity-update-case",[],[]],[{"c":"5.5.11.3\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"}],["#tabbatch-entity-update-case",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatch-entity-delete-case",[],[]],[{"c":"5.5.11.4\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Delete","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"}],["#tabbatch-entity-delete-case",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbatch-entity-merge-case",[],[]],[{"c":"5.5.11.5\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Merge","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"}],["#tabbatch-entity-merge-case",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabmerge-patch-behaviour",[],[]],[{"c":"5.5.12\tMerge","t":"Str"},{"t":"Space"},{"c":"Patch","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabmerge-patch-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablimiting-operations-to-local-scope",[],[]],[{"c":"5.5.13","t":"Str"},{"c":"\tLimiting","t":"Str"},{"t":"Space"},{"c":"operations","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"local","t":"Str"},{"t":"Space"},{"c":"scope","t":"Str"}],["#tablimiting-operations-to-local-scope",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdistributed-transactional-behaviour",[],[]],[{"c":"5.5.14\tDistributed","t":"Str"},{"t":"Space"},{"c":"Transactional","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabdistributed-transactional-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsnapshot-behaviour",[],[]],[{"c":"5.5.15\tSnapshot","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabsnapshot-behaviour",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-information-provision",[],[]],[{"c":"5.6\tContext","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Provision","t":"Str"}],["#tabcontext-information-provision",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabcreate-entity",[],[]],[{"c":"5.6.1\tCreate","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabcreate-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription",[],[]],[{"c":"5.6.1.1\tDescription","t":"Str"}],["#tabdescription",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram",[],[]],[{"c":"5.6.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data",[],[]],[{"c":"5.6.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour",[],[]],[{"c":"5.6.1.4\tBehaviour","t":"Str"}],["#tabbehaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data",[],[]],[{"c":"5.6.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-attributes",[],[]],[{"c":"5.6.2\tUpdate","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabupdate-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-1",[],[]],[{"c":"5.6.2.1\tDescription","t":"Str"}],["#tabdescription-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-1",[],[]],[{"c":"5.6.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-1",[],[]],[{"c":"5.6.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-1",[],[]],[{"c":"5.6.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-1",[],[]],[{"c":"5.6.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-1",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabappend-attributes",[],[]],[{"c":"5.6.3\tAppend","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabappend-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-2",[],[]],[{"c":"5.6.3.1\tDescription","t":"Str"}],["#tabdescription-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-2",[],[]],[{"c":"5.6.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-2",[],[]],[{"c":"5.6.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-2",[],[]],[{"c":"5.6.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-2",[],[]],[{"c":"5.6.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-2",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabpartial-attribute-update",[],[]],[{"c":"5.6.4\tPartial","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"update","t":"Str"}],["#tabpartial-attribute-update",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-3",[],[]],[{"c":"5.6.4.1\tDescription","t":"Str"}],["#tabdescription-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-3",[],[]],[{"c":"5.6.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-3",[],[]],[{"c":"5.6.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-3",[],[]],[{"c":"5.6.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-3",[],[]],[{"c":"5.6.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-3",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-attribute",[],[]],[{"c":"5.6.5\tDelete","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"}],["#tabdelete-attribute",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-4",[],[]],[{"c":"5.6.5.1\tDescription","t":"Str"}],["#tabdescription-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-4",[],[]],[{"c":"5.6.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-4",[],[]],[{"c":"5.6.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-4",[],[]],[{"c":"5.6.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-4",[],[]],[{"c":"5.6.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-4",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-entity",[],[]],[{"c":"5.6.6\tDelete","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabdelete-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-5",[],[]],[{"c":"5.6.6.1\tDescription","t":"Str"}],["#tabdescription-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-5",[],[]],[{"c":"5.6.6.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-5",[],[]],[{"c":"5.6.6.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-5",[],[]],[{"c":"5.6.6.4\tBehaviour","t":"Str"}],["#tabbehaviour-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-5",[],[]],[{"c":"5.6.6.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-5",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabbatch-entity-creation",[],[]],[{"c":"5.6.7\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Creation","t":"Str"}],["#tabbatch-entity-creation",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-6",[],[]],[{"c":"5.6.7.1\tDescription","t":"Str"}],["#tabdescription-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-6",[],[]],[{"c":"5.6.7.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-6",[],[]],[{"c":"5.6.7.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-6",[],[]],[{"c":"5.6.7.4\tBehaviour","t":"Str"}],["#tabbehaviour-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-6",[],[]],[{"c":"5.6.7.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-6",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabbatch-entity-creation-or-update-upsert",[],[]],[{"c":"5.6.8\t","t":"Str"},{"c":"Batch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Creation","t":"Str"},{"t":"Space"},{"c":"or","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"},{"t":"Space"},{"c":"(Upsert)","t":"Str"}],["#tabbatch-entity-creation-or-update-upsert",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-7",[],[]],[{"c":"5.6.8.1\tDescription","t":"Str"}],["#tabdescription-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-7",[],[]],[{"c":"5.6.8.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-7",[],[]],[{"c":"5.6.8.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-7",[],[]],[{"c":"5.6.8.4\tBehaviour","t":"Str"}],["#tabbehaviour-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-7",[],[]],[{"c":"5.6.8.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-7",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabbatch-entity-update",[],[]],[{"c":"5.6.9\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"}],["#tabbatch-entity-update",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-8",[],[]],[{"c":"5.6.9.1\tDescription","t":"Str"}],["#tabdescription-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-8",[],[]],[{"c":"5.6.9.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-8",[],[]],[{"c":"5.6.9.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-8",[],[]],[{"c":"5.6.9.4\tBehaviour","t":"Str"}],["#tabbehaviour-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-8",[],[]],[{"c":"5.6.9.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-8",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabbatch-entity-delete",[],[]],[{"c":"5.6.10\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Delete","t":"Str"}],["#tabbatch-entity-delete",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-9",[],[]],[{"c":"5.6.10.1\tDescription","t":"Str"}],["#tabdescription-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-9",[],[]],[{"c":"5.6.10.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-9",[],[]],[{"c":"5.6.10.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-9",[],[]],[{"c":"5.6.10.4\tBehaviour","t":"Str"}],["#tabbehaviour-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-9",[],[]],[{"c":"5.6.10.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-9",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcreate-or-update-upsert-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.11\tCreate","t":"Str"},{"t":"Space"},{"c":"or","t":"Str"},{"t":"Space"},{"c":"Update","t":"Str"},{"t":"Space"},{"c":"(Upsert)","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabcreate-or-update-upsert-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-10",[],[]],[{"c":"5.6.11.1\tDescription","t":"Str"}],["#tabdescription-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-10",[],[]],[{"c":"5.6.11.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-10",[],[]],[{"c":"5.6.11.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-10",[],[]],[{"c":"5.6.11.4\tBehaviour","t":"Str"}],["#tabbehaviour-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-10",[],[]],[{"c":"5.6.11.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-10",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabadd-attributes-to-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.12\tAdd","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabadd-attributes-to-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-11",[],[]],[{"c":"5.6.12.1\tDescription","t":"Str"}],["#tabdescription-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-11",[],[]],[{"c":"5.6.12.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-11",[],[]],[{"c":"5.6.12.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-11",[],[]],[{"c":"5.6.12.4\tBehaviour","t":"Str"}],["#tabbehaviour-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-11",[],[]],[{"c":"5.6.12.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-11",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-attribute-from-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.13\tDelete","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"from","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabdelete-attribute-from-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-12",[],[]],[{"c":"5.6.13.1\tDescription","t":"Str"}],["#tabdescription-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-12",[],[]],[{"c":"5.6.13.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-12",[],[]],[{"c":"5.6.13.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-12",[],[]],[{"c":"5.6.13.4\tBehaviour","t":"Str"}],["#tabbehaviour-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-12",[],[]],[{"c":"5.6.13.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-12",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabmodify-attribute-instance-in-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.14\tModify","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"instance","t":"Str"},{"t":"Space"},{"c":"in","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-13",[],[]],[{"c":"5.6.14.1\tDescription","t":"Str"}],["#tabdescription-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-13",[],[]],[{"c":"5.6.14.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-13",[],[]],[{"c":"5.6.14.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-13",[],[]],[{"c":"5.6.14.4\tBehaviour","t":"Str"}],["#tabbehaviour-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-13",[],[]],[{"c":"5.6.14.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-13",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-attribute-instance-from-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.15\t","t":"Str"},{"c":"Delete","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"instance","t":"Str"},{"t":"Space"},{"c":"from","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-14",[],[]],[{"c":"5.6.15.1\tDescription","t":"Str"}],["#tabdescription-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-14",[],[]],[{"c":"5.6.15.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-14",[],[]],[{"c":"5.6.15.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-14",[],[]],[{"c":"5.6.15.4\tBehaviour","t":"Str"}],["#tabbehaviour-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-14",[],[]],[{"c":"5.6.15.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-14",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-temporal-evolution-of-an-entity",[],[]],[{"c":"5.6.16\tDelete","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabdelete-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-15",[],[]],[{"c":"5.6.16.1\tDescription","t":"Str"}],["#tabdescription-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-15",[],[]],[{"c":"5.6.16.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-15",[],[]],[{"c":"5.6.16.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-15",[],[]],[{"c":"5.6.16.4\tBehaviour","t":"Str"}],["#tabbehaviour-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-15",[],[]],[{"c":"5.6.16.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-15",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabmerge-entity",[],[]],[{"c":"5.6.17\tMerge","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabmerge-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-16",[],[]],[{"c":"5.6.17.1\tDescription","t":"Str"}],["#tabdescription-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-16",[],[]],[{"c":"5.6.17.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-16",[],[]],[{"c":"5.6.17.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-16",[],[]],[{"c":"5.6.17.4\tBehaviour","t":"Str"}],["#tabbehaviour-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-16",[],[]],[{"c":"5.6.17.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-16",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabreplace-entity",[],[]],[{"c":"5.6.18\tReplace","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabreplace-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-17",[],[]],[{"c":"5.6.18.1\tDescription","t":"Str"}],["#tabdescription-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-17",[],[]],[{"c":"5.6.18.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-17",[],[]],[{"c":"5.6.18.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-17",[],[]],[{"c":"5.6.18.4\tBehaviour","t":"Str"}],["#tabbehaviour-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-17",[],[]],[{"c":"5.6.18.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-17",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabreplace-attribute",[],[]],[{"c":"5.6.19\tReplace","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"}],["#tabreplace-attribute",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-18",[],[]],[{"c":"5.6.19.1\tDescription","t":"Str"}],["#tabdescription-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-18",[],[]],[{"c":"5.6.19.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-18",[],[]],[{"c":"5.6.19.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-18",[],[]],[{"c":"5.6.19.4\tBehaviour","t":"Str"}],["#tabbehaviour-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-18",[],[]],[{"c":"5.6.19.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-18",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabbatch-entity-merge",[],[]],[{"c":"5.6.20\tBatch","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Merge","t":"Str"}],["#tabbatch-entity-merge",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-19",[],[]],[{"c":"5.6.20.1\tDescription","t":"Str"}],["#tabdescription-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-19",[],[]],[{"c":"5.6.20.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-19",[],[]],[{"c":"5.6.20.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-19",[],[]],[{"c":"5.6.20.4\tBehaviour","t":"Str"}],["#tabbehaviour-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-19",[],[]],[{"c":"5.6.20.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-19",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabpurge-entities",[],[]],[{"c":"5.6.21\tPurge","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabpurge-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-20",[],[]],[{"c":"5.6.21.1\tDescription","t":"Str"}],["#tabdescription-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-20",[],[]],[{"c":"5.6.21.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-20",[],[]],[{"c":"5.6.21.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-20",[],[]],[{"c":"5.6.21.4\tBehaviour","t":"Str"}],["#tabbehaviour-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-20",[],[]],[{"c":"5.6.21.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-20",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-information-consumption",[],[]],[{"c":"5.7\tContext","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Consumption","t":"Str"}],["#tabcontext-information-consumption",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabretrieve-entity",[],[]],[{"c":"5.7.1\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabretrieve-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-21",[],[]],[{"c":"5.7.1.1\tDescription","t":"Str"}],["#tabdescription-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-21",[],[]],[{"c":"5.7.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-21",[],[]],[{"c":"5.7.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-21",[],[]],[{"c":"5.7.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-21",[],[]],[{"c":"5.7.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-21",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabquery-entities",[],[]],[{"c":"5.7.2\tQuery","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabquery-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-22",[],[]],[{"c":"5.7.2.1\tDescription","t":"Str"}],["#tabdescription-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-22",[],[]],[{"c":"5.7.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-22",[],[]],[{"c":"5.7.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-22",[],[]],[{"c":"5.7.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-22",[],[]],[{"c":"5.7.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-22",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-temporal-evolution-of-an-entity",[],[]],[{"c":"5.7.3\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#tabretrieve-temporal-evolution-of-an-entity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-23",[],[]],[{"c":"5.7.3.1\tDescription","t":"Str"}],["#tabdescription-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-23",[],[]],[{"c":"5.7.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-23",[],[]],[{"c":"5.7.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-23",[],[]],[{"c":"5.7.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-23",[],[]],[{"c":"5.7.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-23",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabquery-temporal-evolution-of-entities",[],[]],[{"c":"5.7.4\tQuery","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabquery-temporal-evolution-of-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-24",[],[]],[{"c":"5.7.4.1\tDescription","t":"Str"}],["#tabdescription-24",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-24",[],[]],[{"c":"5.7.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-24",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-24",[],[]],[{"c":"5.7.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-24",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-24",[],[]],[{"c":"5.7.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-24",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-24",[],[]],[{"c":"5.7.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"Data","t":"Str"}],["#taboutput-data-24",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-available-entity-types",[],[]],[{"c":"5.7.5\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#tabretrieve-available-entity-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-25",[],[]],[{"c":"5.7.5.1\tDescription","t":"Str"}],["#tabdescription-25",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-25",[],[]],[{"c":"5.7.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-25",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-25",[],[]],[{"c":"5.7.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-25",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-25",[],[]],[{"c":"5.7.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-25",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-25",[],[]],[{"c":"5.7.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-25",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-details-of-available-entity-types",[],[]],[{"c":"5.7.6\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Details","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#tabretrieve-details-of-available-entity-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-26",[],[]],[{"c":"5.7.6.1\tDescription","t":"Str"}],["#tabdescription-26",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-26",[],[]],[{"c":"5.7.6.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-26",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-26",[],[]],[{"c":"5.7.6.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-26",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-26",[],[]],[{"c":"5.7.6.4\tBehaviour","t":"Str"}],["#tabbehaviour-26",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-26",[],[]],[{"c":"5.7.6.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-26",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-available-entity-type-information",[],[]],[{"c":"5.7.7\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#tabretrieve-available-entity-type-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-27",[],[]],[{"c":"5.7.7.1\tDescription","t":"Str"}],["#tabdescription-27",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-27",[],[]],[{"c":"5.7.7.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-27",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-27",[],[]],[{"c":"5.7.7.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-27",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-27",[],[]],[{"c":"5.7.7.4\tBehaviour","t":"Str"}],["#tabbehaviour-27",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-27",[],[]],[{"c":"5.7.7.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-27",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-available-attributes",[],[]],[{"c":"5.7.8\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabretrieve-available-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-28",[],[]],[{"c":"5.7.8.1\tDescription","t":"Str"}],["#tabdescription-28",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-28",[],[]],[{"c":"5.7.8.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-28",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-28",[],[]],[{"c":"5.7.8.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-28",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-28",[],[]],[{"c":"5.7.8.4\tBehaviour","t":"Str"}],["#tabbehaviour-28",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-28",[],[]],[{"c":"5.7.8.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-28",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-details-of-available-attributes",[],[]],[{"c":"5.7.9\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Details","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabretrieve-details-of-available-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-29",[],[]],[{"c":"5.7.9.1\tDescription","t":"Str"}],["#tabdescription-29",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-29",[],[]],[{"c":"5.7.9.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-29",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-29",[],[]],[{"c":"5.7.9.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-29",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-29",[],[]],[{"c":"5.7.9.4\tBehaviour","t":"Str"}],["#tabbehaviour-29",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-29",[],[]],[{"c":"5.7.9.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-29",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-available-attribute-information",[],[]],[{"c":"5.7.10\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#tabretrieve-available-attribute-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-30",[],[]],[{"c":"5.7.10.1\tDescription","t":"Str"}],["#tabdescription-30",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-30",[],[]],[{"c":"5.7.10.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-30",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-30",[],[]],[{"c":"5.7.10.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-30",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-30",[],[]],[{"c":"5.7.10.4\tBehaviour","t":"Str"}],["#tabbehaviour-30",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-30",[],[]],[{"c":"5.7.10.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-30",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes",[],[]],[{"c":"5.7.11\tArchitecture-related","t":"Str"},{"t":"Space"},{"c":"aspects","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"retrieval","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-information-subscription",[],[]],[{"c":"5.8\tContext","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabcontext-information-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabcreate-subscription",[],[]],[{"c":"5.8.1\tCreate","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabcreate-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-31",[],[]],[{"c":"5.8.1.1\tDescription","t":"Str"}],["#tabdescription-31",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-31",[],[]],[{"c":"5.8.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-31",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-31",[],[]],[{"c":"5.8.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-31",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-31",[],[]],[{"c":"5.8.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-31",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-31",[],[]],[{"c":"5.8.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-31",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-subscription",[],[]],[{"c":"5.8.2\tUpdate","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabupdate-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-32",[],[]],[{"c":"5.8.2.1\tDescription","t":"Str"}],["#tabdescription-32",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-32",[],[]],[{"c":"5.8.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-32",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-32",[],[]],[{"c":"5.8.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-32",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-32",[],[]],[{"c":"5.8.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-32",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-32",[],[]],[{"c":"5.8.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-32",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-subscription",[],[]],[{"c":"5.8.3\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabretrieve-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-33",[],[]],[{"c":"5.8.3.1\tDescription","t":"Str"}],["#tabdescription-33",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-33",[],[]],[{"c":"5.8.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-33",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-33",[],[]],[{"c":"5.8.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-33",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-33",[],[]],[{"c":"5.8.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-33",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-33",[],[]],[{"c":"5.8.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-33",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabquery-subscriptions",[],[]],[{"c":"5.8.4\tQuery","t":"Str"},{"t":"Space"},{"c":"Subscriptions","t":"Str"}],["#tabquery-subscriptions",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-34",[],[]],[{"c":"5.8.4.1\tDescription","t":"Str"}],["#tabdescription-34",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-34",[],[]],[{"c":"5.8.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-34",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-34",[],[]],[{"c":"5.8.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-34",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-34",[],[]],[{"c":"5.8.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-34",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-34",[],[]],[{"c":"5.8.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-34",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-subscription",[],[]],[{"c":"5.8.5\tDelete","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabdelete-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-35",[],[]],[{"c":"5.8.5.1\tDescription","t":"Str"}],["#tabdescription-35",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-35",[],[]],[{"c":"5.8.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-35",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-35",[],[]],[{"c":"5.8.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-35",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-35",[],[]],[{"c":"5.8.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-35",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-35",[],[]],[{"c":"5.8.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-35",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabnotification-behaviour",[],[]],[{"c":"5.8.6\tNotification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabnotification-behaviour",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-source-registration",[],[]],[{"c":"5.9\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"}],["#tabcontext-source-registration",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-18",[],[]],[{"c":"5.9.1\tIntroduction","t":"Str"}],["#tabintroduction-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabregister-context-source",[],[]],[{"c":"5.9.2\tRegister","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"}],["#tabregister-context-source",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-36",[],[]],[{"c":"5.9.2.1\tDescription","t":"Str"}],["#tabdescription-36",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-36",[],[]],[{"c":"5.9.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-36",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-36",[],[]],[{"c":"5.9.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-36",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-36",[],[]],[{"c":"5.9.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-36",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-36",[],[]],[{"c":"5.9.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-36",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-context-source-registration",[],[]],[{"c":"5.9.3\tUpdate","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"}],["#tabupdate-context-source-registration",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-37",[],[]],[{"c":"5.9.3.1\tDescription","t":"Str"}],["#tabdescription-37",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-37",[],[]],[{"c":"5.9.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-37",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-37",[],[]],[{"c":"5.9.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-37",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-37",[],[]],[{"c":"5.9.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-37",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-37",[],[]],[{"c":"5.9.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-37",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-context-source-registration",[],[]],[{"c":"5.9.4\tDelete","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"}],["#tabdelete-context-source-registration",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-38",[],[]],[{"c":"5.9.4.1\tDescription","t":"Str"}],["#tabdescription-38",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-38",[],[]],[{"c":"5.9.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-38",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-38",[],[]],[{"c":"5.9.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-38",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-38",[],[]],[{"c":"5.9.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-38",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-38",[],[]],[{"c":"5.9.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-38",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-source-discovery",[],[]],[{"c":"5.10\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Discovery","t":"Str"}],["#tabcontext-source-discovery",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabretrieve-context-source-registration",[],[]],[{"c":"5.10.1\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"}],["#tabretrieve-context-source-registration",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-39",[],[]],[{"c":"5.10.1.1\tDescription","t":"Str"}],["#tabdescription-39",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-39",[],[]],[{"c":"5.10.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-39",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-39",[],[]],[{"c":"5.10.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-39",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-39",[],[]],[{"c":"5.10.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-39",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-39",[],[]],[{"c":"5.10.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-39",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabquery-context-source-registrations",[],[]],[{"c":"5.10.2\tQuery","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registrations","t":"Str"}],["#tabquery-context-source-registrations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-40",[],[]],[{"c":"5.10.2.1\tDescription","t":"Str"}],["#tabdescription-40",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-40",[],[]],[{"c":"5.10.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-40",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-40",[],[]],[{"c":"5.10.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-40",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-40",[],[]],[{"c":"5.10.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-40",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-40",[],[]],[{"c":"5.10.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-40",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-source-registration-subscription",[],[]],[{"c":"5.11\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabcontext-source-registration-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-19",[],[]],[{"c":"5.11.1\tIntroduction","t":"Str"}],["#tabintroduction-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcreate-context-source-registration-subscription",[],[]],[{"c":"5.11.2\tCreate","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabcreate-context-source-registration-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-41",[],[]],[{"c":"5.11.2.1\tDescription","t":"Str"}],["#tabdescription-41",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-41",[],[]],[{"c":"5.11.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-41",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-41",[],[]],[{"c":"5.11.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-41",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-41",[],[]],[{"c":"5.11.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-41",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-41",[],[]],[{"c":"5.11.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-41",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-context-source-registration-subscription",[],[]],[{"c":"5.11.3\tUpdate","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabupdate-context-source-registration-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-42",[],[]],[{"c":"5.11.3.1\tDescription","t":"Str"}],["#tabdescription-42",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-42",[],[]],[{"c":"5.11.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-42",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-42",[],[]],[{"c":"5.11.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-42",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-42",[],[]],[{"c":"5.11.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-42",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-42",[],[]],[{"c":"5.11.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-42",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-context-source-registration-subscription",[],[]],[{"c":"5.11.4\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabretrieve-context-source-registration-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-43",[],[]],[{"c":"5.11.4.1\tDescription","t":"Str"}],["#tabdescription-43",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-43",[],[]],[{"c":"5.11.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-43",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-43",[],[]],[{"c":"5.11.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-43",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-43",[],[]],[{"c":"5.11.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-43",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-43",[],[]],[{"c":"5.11.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-43",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabquery-context-source-registration-subscriptions",[],[]],[{"c":"5.11.5\tQuery","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscriptions","t":"Str"}],["#tabquery-context-source-registration-subscriptions",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-44",[],[]],[{"c":"5.11.5.1\tDescription","t":"Str"}],["#tabdescription-44",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-44",[],[]],[{"c":"5.11.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-44",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-44",[],[]],[{"c":"5.11.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-44",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-44",[],[]],[{"c":"5.11.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-44",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-44",[],[]],[{"c":"5.11.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-44",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-context-source-registration-subscription",[],[]],[{"c":"5.11.6\tDelete","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#tabdelete-context-source-registration-subscription",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-45",[],[]],[{"c":"5.11.6.1\tDescription","t":"Str"}],["#tabdescription-45",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-45",[],[]],[{"c":"5.11.6.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-45",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-45",[],[]],[{"c":"5.11.6.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-45",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-45",[],[]],[{"c":"5.11.6.4\tBehaviour","t":"Str"}],["#tabbehaviour-45",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-45",[],[]],[{"c":"5.11.6.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-45",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabnotification-behaviour-1",[],[]],[{"c":"5.11.7\tNotification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabnotification-behaviour-1",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabmatching-context-source-registrations",[],[]],[{"c":"5.12\tMatching","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registrations","t":"Str"}],["#tabmatching-context-source-registrations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabstoring-managing-and-serving-contexts",[],[]],[{"c":"5.13\tStoring,","t":"Str"},{"t":"Space"},{"c":"Managing","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Serving","t":"Str"},{"t":"Space"},{"c":"@contexts","t":"Str"}],["#tabstoring-managing-and-serving-contexts",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-20",[],[]],[{"c":"5.13.1\tIntroduction","t":"Str"}],["#tabintroduction-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabadd-context",[],[]],[{"c":"5.13.2\tAdd","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"}],["#tabadd-context",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-46",[],[]],[{"c":"5.13.2.1\tDescription","t":"Str"}],["#tabdescription-46",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-46",[],[]],[{"c":"5.13.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-46",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-46",[],[]],[{"c":"5.13.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-46",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-46",[],[]],[{"c":"5.13.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-46",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-46",[],[]],[{"c":"5.13.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-46",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tablist-contexts",[],[]],[{"c":"5.13.3\tList","t":"Str"},{"t":"Space"},{"c":"@contexts","t":"Str"}],["#tablist-contexts",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-47",[],[]],[{"c":"5.13.3.1\tDescription","t":"Str"}],["#tabdescription-47",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-47",[],[]],[{"c":"5.13.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-47",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-47",[],[]],[{"c":"5.13.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-47",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-47",[],[]],[{"c":"5.13.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-47",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-47",[],[]],[{"c":"5.13.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-47",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabserve-context",[],[]],[{"c":"5.13.4\tServe","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"}],["#tabserve-context",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-48",[],[]],[{"c":"5.13.4.1\tDescription","t":"Str"}],["#tabdescription-48",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-48",[],[]],[{"c":"5.13.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-48",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-48",[],[]],[{"c":"5.13.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-48",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-48",[],[]],[{"c":"5.13.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-48",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-48",[],[]],[{"c":"5.13.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-48",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-and-reload-context",[],[]],[{"c":"5.13.5\tDelete","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Reload","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"}],["#tabdelete-and-reload-context",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-49",[],[]],[{"c":"5.13.5.1\tDescription","t":"Str"}],["#tabdescription-49",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-49",[],[]],[{"c":"5.13.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-49",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-49",[],[]],[{"c":"5.13.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-49",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-49",[],[]],[{"c":"5.13.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-49",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-49",[],[]],[{"c":"5.13.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-49",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-source-entity-mapping",[],[]],[{"c":"5.14\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Mapping","t":"Str"}],["#tabcontext-source-entity-mapping",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabretrieve-entitymap",[],[]],[{"c":"5.14.1\tRetrieve","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"}],["#tabretrieve-entitymap",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-50",[],[]],[{"c":"5.14.1.1\tDescription","t":"Str"}],["#tabdescription-50",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-50",[],[]],[{"c":"5.14.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-50",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-50",[],[]],[{"c":"5.14.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-50",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-50",[],[]],[{"c":"5.14.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-50",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-50",[],[]],[{"c":"5.14.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-50",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-entitymap",[],[]],[{"c":"5.14.2\tUpdate","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"}],["#tabupdate-entitymap",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-51",[],[]],[{"c":"5.14.2.1\tDescription","t":"Str"}],["#tabdescription-51",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-51",[],[]],[{"c":"5.14.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-51",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-51",[],[]],[{"c":"5.14.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-51",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-51",[],[]],[{"c":"5.14.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-51",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-51",[],[]],[{"c":"5.14.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-51",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabdelete-entitymap",[],[]],[{"c":"5.14.3\tDelete","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"}],["#tabdelete-entitymap",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-52",[],[]],[{"c":"5.14.3.1\tDescription","t":"Str"}],["#tabdescription-52",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-52",[],[]],[{"c":"5.14.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-52",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-52",[],[]],[{"c":"5.14.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-52",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-52",[],[]],[{"c":"5.14.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-52",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-52",[],[]],[{"c":"5.14.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-52",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcreate-entitymap-for-query-entities",[],[]],[{"c":"5.14.4\tCreate","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabcreate-entitymap-for-query-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-53",[],[]],[{"c":"5.14.4.1\tDescription","t":"Str"}],["#tabdescription-53",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-53",[],[]],[{"c":"5.14.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-53",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-53",[],[]],[{"c":"5.14.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-53",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-53",[],[]],[{"c":"5.14.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-53",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-53",[],[]],[{"c":"5.14.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-53",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcreate-entitymap-for-query-temporal-evolution-of-entities",[],[]],[{"c":"5.14.5\tCreate","t":"Str"},{"t":"Space"},{"c":"EntityMap","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"Temporal","t":"Str"},{"t":"Space"},{"c":"Evolution","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabcreate-entitymap-for-query-temporal-evolution-of-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-54",[],[]],[{"c":"5.14.5.1\tDescription","t":"Str"}],["#tabdescription-54",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-54",[],[]],[{"c":"5.14.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-54",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-54",[],[]],[{"c":"5.14.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-54",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-54",[],[]],[{"c":"5.14.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-54",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-54",[],[]],[{"c":"5.7.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"Data","t":"Str"}],["#taboutput-data-54",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabcontext-source-identity-information",[],[]],[{"c":"5.15\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Identity","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#tabcontext-source-identity-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabretrieve-context-source-identity-information",[],[]],[{"c":"5.15.1\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Identity","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#tabretrieve-context-source-identity-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-55",[],[]],[{"c":"5.15.1.1\tDescription","t":"Str"}],["#tabdescription-55",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-55",[],[]],[{"c":"5.15.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-55",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-55",[],[]],[{"c":"5.15.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-55",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-55",[],[]],[{"c":"5.15.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-55",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-55",[],[]],[{"c":"5.15.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-55",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabsnapshot-functionality",[],[]],[{"c":"5.16\tSnapshot","t":"Str"},{"t":"Space"},{"c":"Functionality","t":"Str"}],["#tabsnapshot-functionality",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabcreate-snapshot",[],[]],[{"c":"5.16.1\tCreate","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"}],["#tabcreate-snapshot",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-56",[],[]],[{"c":"5.16.1.1\tDescription","t":"Str"}],["#tabdescription-56",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-56",[],[]],[{"c":"5.16.1.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-56",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-56",[],[]],[{"c":"5.16.1.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-56",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-56",[],[]],[{"c":"5.16.1.4\tBehaviour","t":"Str"}],["#tabbehaviour-56",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-56",[],[]],[{"c":"5.16.1.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-56",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabclone-snapshot",[],[]],[{"c":"5.16.2\tClone","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"}],["#tabclone-snapshot",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-57",[],[]],[{"c":"5.16.2.1\tDescription","t":"Str"}],["#tabdescription-57",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-57",[],[]],[{"c":"5.16.2.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-57",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-57",[],[]],[{"c":"5.16.2.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-57",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-57",[],[]],[{"c":"5.16.2.4\tBehaviour","t":"Str"}],["#tabbehaviour-57",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-57",[],[]],[{"c":"5.16.2.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-57",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabretrieve-snapshot-status",[],[]],[{"c":"5.16.3\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"},{"t":"Space"},{"c":"Status","t":"Str"}],["#tabretrieve-snapshot-status",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-58",[],[]],[{"c":"5.16.3.1\tDescription","t":"Str"}],["#tabdescription-58",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-58",[],[]],[{"c":"5.16.3.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-58",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-58",[],[]],[{"c":"5.16.3.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-58",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-58",[],[]],[{"c":"5.16.3.4\tBehaviour","t":"Str"}],["#tabbehaviour-58",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-58",[],[]],[{"c":"5.16.3.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-58",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabupdate-snapshot-status",[],[]],[{"c":"5.16.4\tUpdate","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"},{"t":"Space"},{"c":"Status","t":"Str"}],["#tabupdate-snapshot-status",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-59",[],[]],[{"c":"5.16.4.1\tDescription","t":"Str"}],["#tabdescription-59",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-59",[],[]],[{"c":"5.16.4.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-59",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-59",[],[]],[{"c":"5.16.4.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-59",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-59",[],[]],[{"c":"5.16.4.4\tBehaviour","t":"Str"}],["#tabbehaviour-59",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-59",[],[]],[{"c":"5.16.4.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-59",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-a-json-ld-object-representing-the-snapshot-status-as-mandated-by-clause-5.2.41.5.16.5tabdelete-snapshot",[],[]],[{"c":"A","t":"Str"},{"t":"Space"},{"c":"JSON-LD","t":"Str"},{"t":"Space"},{"c":"object","t":"Str"},{"t":"Space"},{"c":"representing","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"},{"t":"Space"},{"c":"status","t":"Str"},{"t":"Space"},{"c":"as","t":"Str"},{"t":"Space"},{"c":"mandated","t":"Str"},{"t":"Space"},{"c":"by","t":"Str"},{"t":"Space"},{"c":"clause","t":"Str"},{"t":"Space"},{"c":"5.2.41.5.16.5\tDelete","t":"Str"},{"t":"Space"},{"c":"Snapshot","t":"Str"}],["#a-json-ld-object-representing-the-snapshot-status-as-mandated-by-clause-5.2.41.5.16.5tabdelete-snapshot",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-60",[],[]],[{"c":"5.16.5.1\tDescription","t":"Str"}],["#tabdescription-60",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-60",[],[]],[{"c":"5.16.5.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-60",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-60",[],[]],[{"c":"5.16.5.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-60",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-60",[],[]],[{"c":"5.16.5.4\tBehaviour","t":"Str"}],["#tabbehaviour-60",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-60",[],[]],[{"c":"5.16.5.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-60",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabsnapshot-status-notification-behaviour",[],[]],[{"c":"5.16.6\tSnapshot","t":"Str"},{"t":"Space"},{"c":"status","t":"Str"},{"t":"Space"},{"c":"notification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabsnapshot-status-notification-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpurge-snapshots",[],[]],[{"c":"5.16.7\tPurge","t":"Str"},{"t":"Space"},{"c":"Snapshots","t":"Str"}],["#tabpurge-snapshots",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-61",[],[]],[{"c":"5.16.7.1\tDescription","t":"Str"}],["#tabdescription-61",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabuse-case-diagram-61",[],[]],[{"c":"5.16.7.2\tUse","t":"Str"},{"t":"Space"},{"c":"case","t":"Str"},{"t":"Space"},{"c":"diagram","t":"Str"}],["#tabuse-case-diagram-61",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinput-data-61",[],[]],[{"c":"5.16.7.3\tInput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#tabinput-data-61",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabbehaviour-61",[],[]],[{"c":"5.16.7.4\tBehaviour","t":"Str"}],["#tabbehaviour-61",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboutput-data-61",[],[]],[{"c":"5.16.7.5\tOutput","t":"Str"},{"t":"Space"},{"c":"data","t":"Str"}],["#taboutput-data-61",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabapi-http-binding",[],[]],[{"c":"6\tAPI","t":"Str"},{"t":"Space"},{"c":"HTTP","t":"Str"},{"t":"Space"},{"c":"Binding","t":"Str"}],["#tabapi-http-binding",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-21",[],[]],[{"c":"6.1\tIntroduction","t":"Str"}],["#tabintroduction-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabglobal-definitions-and-resource-structure",[],[]],[{"c":"6.2\tGlobal","t":"Str"},{"t":"Space"},{"c":"Definitions","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Resource","t":"Str"},{"t":"Space"},{"c":"Structure","t":"Str"}],["#tabglobal-definitions-and-resource-structure",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcommon-behaviours-1",[],[]],[{"c":"6.3\tCommon","t":"Str"},{"t":"Space"},{"c":"Behaviours","t":"Str"}],["#tabcommon-behaviours-1",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-22",[],[]],[{"c":"6.3.1\tIntroduction","t":"Str"}],["#tabintroduction-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taberror-types-1",[],[]],[{"c":"6.3.2\tError","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#taberror-types-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabreporting-errors",[],[]],[{"c":"6.3.3\tReporting","t":"Str"},{"t":"Space"},{"c":"errors","t":"Str"}],["#tabreporting-errors",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabhttp-request-preconditions",[],[]],[{"c":"6.3.4\tHTTP","t":"Str"},{"t":"Space"},{"c":"request","t":"Str"},{"t":"Space"},{"c":"preconditions","t":"Str"}],["#tabhttp-request-preconditions",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabjson-ld-context-resolution",[],[]],[{"c":"6.3.5\tJSON-LD","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"},{"t":"Space"},{"c":"resolution","t":"Str"}],["#tabjson-ld-context-resolution",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabhttp-response-common-requirements",[],[]],[{"c":"6.3.6\tHTTP","t":"Str"},{"t":"Space"},{"c":"response","t":"Str"},{"t":"Space"},{"c":"common","t":"Str"},{"t":"Space"},{"c":"requirements","t":"Str"}],["#tabhttp-response-common-requirements",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabrepresentation-of-entities",[],[]],[{"c":"6.3.7\tRepresentation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabrepresentation-of-entities",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnotification-behaviour-2",[],[]],[{"c":"6.3.8\tNotification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabnotification-behaviour-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcsource-notification-behaviour",[],[]],[{"c":"6.3.9\tCsource","t":"Str"},{"t":"Space"},{"c":"Notification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabcsource-notification-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpagination-behaviour-1",[],[]],[{"c":"6.3.10\tPagination","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabpagination-behaviour-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabincluding-system-attributes",[],[]],[{"c":"6.3.11\tIncluding","t":"Str"},{"t":"Space"},{"c":"system","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#tabincluding-system-attributes",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsimplified-or-aggregated-temporal-representation-of-entities",[],[]],[{"c":"6.3.12\tSimplified","t":"Str"},{"t":"Space"},{"c":"or","t":"Str"},{"t":"Space"},{"c":"aggregated","t":"Str"},{"t":"Space"},{"c":"temporal","t":"Str"},{"t":"Space"},{"c":"representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#tabsimplified-or-aggregated-temporal-representation-of-entities",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabcounting-number-of-results",[],[]],[{"c":"6.3.13\tCounting","t":"Str"},{"t":"Space"},{"c":"number","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"results","t":"Str"}],["#tabcounting-number-of-results",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabtenant-specification",[],[]],[{"c":"6.3.14\tTenant","t":"Str"},{"t":"Space"},{"c":"specification","t":"Str"}],["#tabtenant-specification",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabgeojson-representation-of-spatially-bound-entities",[],[]],[{"c":"6.3.15\tGeoJSON","t":"Str"},{"t":"Space"},{"c":"representation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"spatially","t":"Str"},{"t":"Space"},{"c":"bound","t":"Str"},{"t":"Space"},{"c":"entities","t":"Str"}],["#tabgeojson-representation-of-spatially-bound-entities",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabexpiration-time-for-cached-contexts",[],[]],[{"c":"6.3.16\tExpiration","t":"Str"},{"t":"Space"},{"c":"time","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"cached","t":"Str"},{"t":"Space"},{"c":"@contexts","t":"Str"}],["#tabexpiration-time-for-cached-contexts",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdistributed-operations-caching-and-timeout-behaviour",[],[]],[{"c":"6.3.17\tDistributed","t":"Str"},{"t":"Space"},{"c":"Operations","t":"Str"},{"t":"Space"},{"c":"Caching","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Timeout","t":"Str"},{"t":"Space"},{"c":"Behaviour","t":"Str"}],["#tabdistributed-operations-caching-and-timeout-behaviour",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tablimiting-distributed-operations",[],[]],[{"c":"6.3.18\tLimiting","t":"Str"},{"t":"Space"},{"c":"Distributed","t":"Str"},{"t":"Space"},{"c":"Operations","t":"Str"}],["#tablimiting-distributed-operations",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabextra-information-to-provide-when-contacting-context-source-1",[],[]],[{"c":"6.3.19\tExtra","t":"Str"},{"t":"Space"},{"c":"information","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"provide","t":"Str"},{"t":"Space"},{"c":"when","t":"Str"},{"t":"Space"},{"c":"contacting","t":"Str"},{"t":"Space"},{"c":"Context","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"}],["#tabextra-information-to-provide-when-contacting-context-source-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabinvalid-parameters",[],[]],[{"c":"6.3.20\tInvalid","t":"Str"},{"t":"Space"},{"c":"parameters","t":"Str"}],["#tabinvalid-parameters",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-taboptional-profile-information-regarding-versioning-and-datatype-conformance",[],[]],[{"c":"6.3.21\tOptional","t":"Str"},{"t":"Space"},{"c":"profile","t":"Str"},{"t":"Space"},{"c":"information","t":"Str"},{"t":"Space"},{"c":"regarding","t":"Str"},{"t":"Space"},{"c":"versioning","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"datatype","t":"Str"},{"t":"Space"},{"c":"conformance","t":"Str"}],["#taboptional-profile-information-regarding-versioning-and-datatype-conformance",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabsnapshot-specification",[],[]],[{"c":"6.3.22\tSnapshot","t":"Str"},{"t":"Space"},{"c":"specification","t":"Str"}],["#tabsnapshot-specification",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entities",[],[]],[{"c":"6.4\tResource:","t":"Str"},{"t":"Space"},{"c":"entities/","t":"Str"}],["#tabresource-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-62",[],[]],[{"c":"6.4.1\tDescription","t":"Str"}],["#tabdescription-62",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition",[],[]],[{"c":"6.4.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods",[],[]],[{"c":"6.4.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost",[],[]],[{"c":"6.4.3.1\tPOST","t":"Str"}],["#tabpost",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget",[],[]],[{"c":"6.4.3.2\tGET","t":"Str"}],["#tabget",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete",[],[]],[{"c":"6.4.3.3\tDELETE","t":"Str"}],["#tabdelete",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entitiesentityid",[],[]],[{"c":"6.5\tResource:","t":"Str"},{"t":"Space"},{"c":"entities/{entityId}","t":"Str"}],["#tabresource-entitiesentityid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-63",[],[]],[{"c":"6.5.1\tDescription","t":"Str"}],["#tabdescription-63",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-1",[],[]],[{"c":"6.5.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-1",[],[]],[{"c":"6.5.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-1",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-1",[],[]],[{"c":"6.5.3.1\tGET","t":"Str"}],["#tabget-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-1",[],[]],[{"c":"6.5.3.2\tDELETE","t":"Str"}],["#tabdelete-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabput",[],[]],[{"c":"6.5.3.3\tPUT","t":"Str"}],["#tabput",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch",[],[]],[{"c":"6.5.3.4\tPATCH","t":"Str"}],["#tabpatch",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entitiesentityidattrs",[],[]],[{"c":"6.6\tResource:","t":"Str"},{"t":"Space"},{"c":"entities/{entityId}/attrs/","t":"Str"}],["#tabresource-entitiesentityidattrs",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-64",[],[]],[{"c":"6.6.1\tDescription","t":"Str"}],["#tabdescription-64",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-2",[],[]],[{"c":"6.6.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-2",[],[]],[{"c":"6.6.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-2",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-1",[],[]],[{"c":"6.6.3.1\tPOST","t":"Str"}],["#tabpost-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-1",[],[]],[{"c":"6.6.3.2\tPATCH","t":"Str"}],["#tabpatch-1",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entitiesentityidattrsattrid",[],[]],[{"c":"6.7\tResource:","t":"Str"},{"t":"Space"},{"c":"entities/{entityId}/attrs/{attrId}","t":"Str"}],["#tabresource-entitiesentityidattrsattrid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-65",[],[]],[{"c":"6.7.1\tDescription","t":"Str"}],["#tabdescription-65",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-3",[],[]],[{"c":"6.7.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-3",[],[]],[{"c":"6.7.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-3",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpatch-2",[],[]],[{"c":"6.7.3.1\tPATCH","t":"Str"}],["#tabpatch-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-2",[],[]],[{"c":"6.7.3.2\tDELETE","t":"Str"}],["#tabdelete-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabput-1",[],[]],[{"c":"6.7.3.3\tPUT","t":"Str"}],["#tabput-1",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-csourceregistrations",[],[]],[{"c":"6.8\tResource:","t":"Str"},{"t":"Space"},{"c":"csourceRegistrations/","t":"Str"}],["#tabresource-csourceregistrations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-66",[],[]],[{"c":"6.8.1\tDescription","t":"Str"}],["#tabdescription-66",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-4",[],[]],[{"c":"6.8.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-4",[],[]],[{"c":"6.8.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-4",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-2",[],[]],[{"c":"6.8.3.1\tPOST","t":"Str"}],["#tabpost-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget-2",[],[]],[{"c":"6.8.3.2\tGET","t":"Str"}],["#tabget-2",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-csourceregistrationsregistrationid",[],[]],[{"c":"6.9\tResource:","t":"Str"},{"t":"Space"},{"c":"csourceRegistrations/{registrationId}","t":"Str"}],["#tabresource-csourceregistrationsregistrationid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-67",[],[]],[{"c":"6.9.1\tDescription","t":"Str"}],["#tabdescription-67",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-5",[],[]],[{"c":"6.9.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-5",[],[]],[{"c":"6.9.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-5",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-3",[],[]],[{"c":"6.9.3.1\tGET","t":"Str"}],["#tabget-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-3",[],[]],[{"c":"6.9.3.2\tPATCH","t":"Str"}],["#tabpatch-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-3",[],[]],[{"c":"6.9.3.3\tDELETE","t":"Str"}],["#tabdelete-3",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-subscriptions",[],[]],[{"c":"6.10\tResource:","t":"Str"},{"t":"Space"},{"c":"subscriptions/","t":"Str"}],["#tabresource-subscriptions",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-68",[],[]],[{"c":"6.10.1\tDescription","t":"Str"}],["#tabdescription-68",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-6",[],[]],[{"c":"6.10.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-6",[],[]],[{"c":"6.10.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-6",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-3",[],[]],[{"c":"6.10.3.1\tPOST","t":"Str"}],["#tabpost-3",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget-4",[],[]],[{"c":"6.10.3.2\tGET","t":"Str"}],["#tabget-4",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-subscriptionssubscriptionid",[],[]],[{"c":"6.11\tResource:","t":"Str"},{"t":"Space"},{"c":"subscriptions/{subscriptionId}","t":"Str"}],["#tabresource-subscriptionssubscriptionid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-69",[],[]],[{"c":"6.11.1\tDescription","t":"Str"}],["#tabdescription-69",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-7",[],[]],[{"c":"6.11.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-7",[],[]],[{"c":"6.11.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-7",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-5",[],[]],[{"c":"6.11.3.1\tGET","t":"Str"}],["#tabget-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-4",[],[]],[{"c":"6.11.3.2\tPATCH","t":"Str"}],["#tabpatch-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-4",[],[]],[{"c":"6.11.3.3\tDELETE","t":"Str"}],["#tabdelete-4",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-csourcesubscriptions",[],[]],[{"c":"6.12\tResource:","t":"Str"},{"t":"Space"},{"c":"csourceSubscriptions/","t":"Str"}],["#tabresource-csourcesubscriptions",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-70",[],[]],[{"c":"6.12.1\tDescription","t":"Str"}],["#tabdescription-70",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-8",[],[]],[{"c":"6.12.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-8",[],[]],[{"c":"6.12.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-8",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-4",[],[]],[{"c":"6.12.3.1\tPOST","t":"Str"}],["#tabpost-4",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget-6",[],[]],[{"c":"6.12.3.2\tGET","t":"Str"}],["#tabget-6",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-csourcesubscriptionssubscriptionid",[],[]],[{"c":"6.13\tResource:","t":"Str"},{"t":"Space"},{"c":"csourceSubscriptions/{subscriptionId}","t":"Str"}],["#tabresource-csourcesubscriptionssubscriptionid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-71",[],[]],[{"c":"6.13.1\tDescription","t":"Str"}],["#tabdescription-71",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-9",[],[]],[{"c":"6.13.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-9",[],[]],[{"c":"6.13.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-9",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-7",[],[]],[{"c":"6.13.3.1\tGET","t":"Str"}],["#tabget-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-5",[],[]],[{"c":"6.13.3.2\tPATCH","t":"Str"}],["#tabpatch-5",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-5",[],[]],[{"c":"6.13.3.3\tDELETE","t":"Str"}],["#tabdelete-5",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationscreate",[],[]],[{"c":"6.14\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/create","t":"Str"}],["#tabresource-entityoperationscreate",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-72",[],[]],[{"c":"6.14.1\tDescription","t":"Str"}],["#tabdescription-72",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-10",[],[]],[{"c":"6.14.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-10",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-10",[],[]],[{"c":"6.14.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-10",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-5",[],[]],[{"c":"6.14.3.1\tPOST","t":"Str"}],["#tabpost-5",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationsupsert",[],[]],[{"c":"6.15\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/upsert","t":"Str"}],["#tabresource-entityoperationsupsert",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-73",[],[]],[{"c":"6.15.1\tDescription","t":"Str"}],["#tabdescription-73",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-11",[],[]],[{"c":"6.15.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-11",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-11",[],[]],[{"c":"6.15.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-11",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-6",[],[]],[{"c":"6.15.3.1\tPOST","t":"Str"}],["#tabpost-6",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationsupdate",[],[]],[{"c":"6.16\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/update","t":"Str"}],["#tabresource-entityoperationsupdate",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-74",[],[]],[{"c":"6.16.1\tDescription","t":"Str"}],["#tabdescription-74",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-12",[],[]],[{"c":"6.16.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-12",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-12",[],[]],[{"c":"6.16.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-12",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-7",[],[]],[{"c":"6.16.3.1\tPOST","t":"Str"}],["#tabpost-7",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationsdelete",[],[]],[{"c":"6.17\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/delete","t":"Str"}],["#tabresource-entityoperationsdelete",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-75",[],[]],[{"c":"6.17.1\tDescription","t":"Str"}],["#tabdescription-75",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-13",[],[]],[{"c":"6.17.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-13",[],[]],[{"c":"6.17.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-13",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-8",[],[]],[{"c":"6.17.3.1\tPOST","t":"Str"}],["#tabpost-8",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentities",[],[]],[{"c":"6.18\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entities/","t":"Str"}],["#tabresource-temporalentities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-76",[],[]],[{"c":"6.18.1\tDescription","t":"Str"}],["#tabdescription-76",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-14",[],[]],[{"c":"6.18.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-14",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-14",[],[]],[{"c":"6.18.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-14",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-9",[],[]],[{"c":"6.18.3.1\tPOST","t":"Str"}],["#tabpost-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget-8",[],[]],[{"c":"6.18.3.2\tGET","t":"Str"}],["#tabget-8",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentitiesentityid",[],[]],[{"c":"6.19\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entities/{entityId}","t":"Str"}],["#tabresource-temporalentitiesentityid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-77",[],[]],[{"c":"6.19.1\tDescription","t":"Str"}],["#tabdescription-77",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-15",[],[]],[{"c":"6.19.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-15",[],[]],[{"c":"6.19.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-15",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-9",[],[]],[{"c":"6.19.3.1\tGET","t":"Str"}],["#tabget-9",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-6",[],[]],[{"c":"6.19.3.2\tDELETE","t":"Str"}],["#tabdelete-6",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentitiesentityidattrs",[],[]],[{"c":"6.20\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entities/{entityId}/attrs/","t":"Str"}],["#tabresource-temporalentitiesentityidattrs",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-78",[],[]],[{"c":"6.20.1\tDescription","t":"Str"}],["#tabdescription-78",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-16",[],[]],[{"c":"6.20.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-16",[],[]],[{"c":"6.20.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-16",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-10",[],[]],[{"c":"6.20.3.1\tPOST","t":"Str"}],["#tabpost-10",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentitiesentityidattrsattrid",[],[]],[{"c":"6.21\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entities/{entityId}/attrs/{attrId}","t":"Str"}],["#tabresource-temporalentitiesentityidattrsattrid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-79",[],[]],[{"c":"6.21.1\tDescription","t":"Str"}],["#tabdescription-79",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-17",[],[]],[{"c":"6.21.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-17",[],[]],[{"c":"6.21.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-17",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdelete-7",[],[]],[{"c":"6.21.3.1\tDELETE","t":"Str"}],["#tabdelete-7",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentitiesentityidattrsattrid-instanceid",[],[]],[{"c":"6.22\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entities/{entityId}/attrs/{attrId}/","t":"Str"},{"t":"Space"},{"c":"{instanceId}","t":"Str"}],["#tabresource-temporalentitiesentityidattrsattrid-instanceid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-80",[],[]],[{"c":"6.22.1\tDescription","t":"Str"}],["#tabdescription-80",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-18",[],[]],[{"c":"6.22.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-18",[],[]],[{"c":"6.22.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-18",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpatch-6",[],[]],[{"c":"6.22.3.1\tPATCH","t":"Str"}],["#tabpatch-6",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-8",[],[]],[{"c":"6.22.3.2\tDELETE","t":"Str"}],["#tabdelete-8",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationsquery",[],[]],[{"c":"6.23\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/query","t":"Str"}],["#tabresource-entityoperationsquery",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-81",[],[]],[{"c":"6.23.1\tDescription","t":"Str"}],["#tabdescription-81",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-19",[],[]],[{"c":"6.23.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-19",[],[]],[{"c":"6.23.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-19",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-11",[],[]],[{"c":"6.23.3.1\tPOST","t":"Str"}],["#tabpost-11",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentityoperationsquery",[],[]],[{"c":"6.24\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entityOperations/query","t":"Str"}],["#tabresource-temporalentityoperationsquery",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-82",[],[]],[{"c":"6.24.1\tDescription","t":"Str"}],["#tabdescription-82",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-20",[],[]],[{"c":"6.24.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-20",[],[]],[{"c":"6.24.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-20",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-12",[],[]],[{"c":"6.24.3.1\tPOST","t":"Str"}],["#tabpost-12",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-types",[],[]],[{"c":"6.25\tResource:","t":"Str"},{"t":"Space"},{"c":"types/","t":"Str"}],["#tabresource-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-83",[],[]],[{"c":"6.25.1\tDescription","t":"Str"}],["#tabdescription-83",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-21",[],[]],[{"c":"6.25.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-21",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-21",[],[]],[{"c":"6.25.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-21",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-10",[],[]],[{"c":"6.25.3.1\tGET","t":"Str"}],["#tabget-10",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-typestype",[],[]],[{"c":"6.26\tResource:","t":"Str"},{"t":"Space"},{"c":"types/{type}","t":"Str"}],["#tabresource-typestype",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-84",[],[]],[{"c":"6.26.1\tDescription","t":"Str"}],["#tabdescription-84",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-22",[],[]],[{"c":"6.26.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-22",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-22",[],[]],[{"c":"6.26.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-22",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-11",[],[]],[{"c":"6.26.3.1\tGET","t":"Str"}],["#tabget-11",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-attributes",[],[]],[{"c":"6.27\tResource:","t":"Str"},{"t":"Space"},{"c":"attributes/","t":"Str"}],["#tabresource-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-85",[],[]],[{"c":"6.27.1\tDescription","t":"Str"}],["#tabdescription-85",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-23",[],[]],[{"c":"6.27.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-23",[],[]],[{"c":"6.27.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-23",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-12",[],[]],[{"c":"6.27.3.1\tGET","t":"Str"}],["#tabget-12",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-attributesattrid",[],[]],[{"c":"6.28\tResource:","t":"Str"},{"t":"Space"},{"c":"attributes/{attrId}","t":"Str"}],["#tabresource-attributesattrid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-86",[],[]],[{"c":"6.28.1\tDescription","t":"Str"}],["#tabdescription-86",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-24",[],[]],[{"c":"6.28.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-24",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-24",[],[]],[{"c":"6.28.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-24",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-13",[],[]],[{"c":"6.28.3.1\tGET","t":"Str"}],["#tabget-13",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-jsonldcontexts",[],[]],[{"c":"6.29\tResource:","t":"Str"},{"t":"Space"},{"c":"jsonldContexts/","t":"Str"}],["#tabresource-jsonldcontexts",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-87",[],[]],[{"c":"6.29.1\tDescription","t":"Str"}],["#tabdescription-87",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-25",[],[]],[{"c":"6.29.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-25",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-25",[],[]],[{"c":"6.29.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-25",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-13",[],[]],[{"c":"6.29.3.1\tPOST","t":"Str"}],["#tabpost-13",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabget-14",[],[]],[{"c":"6.29.3.2\tGET","t":"Str"}],["#tabget-14",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-jsonldcontextscontextid",[],[]],[{"c":"6.30\tResource:","t":"Str"},{"t":"Space"},{"c":"jsonldContexts/{contextId}","t":"Str"}],["#tabresource-jsonldcontextscontextid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-88",[],[]],[{"c":"6.30.1\tDescription","t":"Str"}],["#tabdescription-88",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-26",[],[]],[{"c":"6.30.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-26",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-26",[],[]],[{"c":"6.30.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-26",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-15",[],[]],[{"c":"6.30.3.1\tGET","t":"Str"}],["#tabget-15",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-9",[],[]],[{"c":"6.30.3.2\tDELETE","t":"Str"}],["#tabdelete-9",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entityoperationsmerge",[],[]],[{"c":"6.31\tResource:","t":"Str"},{"t":"Space"},{"c":"entityOperations/merge","t":"Str"}],["#tabresource-entityoperationsmerge",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-89",[],[]],[{"c":"6.31.1\tDescription","t":"Str"}],["#tabdescription-89",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-27",[],[]],[{"c":"6.31.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-27",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-27",[],[]],[{"c":"6.31.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-27",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-14",[],[]],[{"c":"6.31.3.1\tPOST","t":"Str"}],["#tabpost-14",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entitymapsentitymapid",[],[]],[{"c":"6.32\tResource:","t":"Str"},{"t":"Space"},{"c":"entityMaps/{entityMapId}","t":"Str"}],["#tabresource-entitymapsentitymapid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-90",[],[]],[{"c":"6.32.1\tDescription","t":"Str"}],["#tabdescription-90",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-28",[],[]],[{"c":"6.32.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-28",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-28",[],[]],[{"c":"6.32.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-28",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-16",[],[]],[{"c":"6.32.3.1\tGET","t":"Str"}],["#tabget-16",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-7",[],[]],[{"c":"6.32.3.2\tPATCH","t":"Str"}],["#tabpatch-7",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-10",[],[]],[{"c":"6.32.3.3\tDELETE","t":"Str"}],["#tabdelete-10",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-infosourceidentity",[],[]],[{"c":"6.33\tResource:","t":"Str"},{"t":"Space"},{"c":"info/sourceIdentity","t":"Str"}],["#tabresource-infosourceidentity",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-91",[],[]],[{"c":"6.33.1\tDescription","t":"Str"}],["#tabdescription-91",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-29",[],[]],[{"c":"6.33.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-29",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-29",[],[]],[{"c":"6.33.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-29",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-17",[],[]],[{"c":"6.33.3.1\tGET","t":"Str"}],["#tabget-17",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-entitymaps",[],[]],[{"c":"6.34\tResource:","t":"Str"},{"t":"Space"},{"c":"entityMaps","t":"Str"}],["#tabresource-entitymaps",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-92",[],[]],[{"c":"6.34.1\tDescription","t":"Str"}],["#tabdescription-92",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-30",[],[]],[{"c":"6.34.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-30",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-30",[],[]],[{"c":"6.34.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-30",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-18",[],[]],[{"c":"6.34.3.1\tGET","t":"Str"}],["#tabget-18",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpost-15",[],[]],[{"c":"6.34.3.2\tPOST","t":"Str"}],["#tabpost-15",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-temporalentitymaps",[],[]],[{"c":"6.35\tResource:","t":"Str"},{"t":"Space"},{"c":"temporal/entityMaps","t":"Str"}],["#tabresource-temporalentitymaps",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-93",[],[]],[{"c":"6.35.1\tDescription","t":"Str"}],["#tabdescription-93",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-31",[],[]],[{"c":"6.35.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-31",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-31",[],[]],[{"c":"6.35.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-31",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-19",[],[]],[{"c":"6.35.3.1\tGET","t":"Str"}],["#tabget-19",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpost-16",[],[]],[{"c":"6.35.3.2\tPOST","t":"Str"}],["#tabpost-16",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-snapshots",[],[]],[{"c":"6.36\tResource:","t":"Str"},{"t":"Space"},{"c":"snapshots","t":"Str"}],["#tabresource-snapshots",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-94",[],[]],[{"c":"6.36.1\tDescription","t":"Str"}],["#tabdescription-94",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-32",[],[]],[{"c":"6.36.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-32",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-32",[],[]],[{"c":"6.36.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-32",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-17",[],[]],[{"c":"6.36.3.1\tPOST","t":"Str"}],["#tabpost-17",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-11",[],[]],[{"c":"6.36.3.2\tDELETE","t":"Str"}],["#tabdelete-11",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-snapshotssnapshotid",[],[]],[{"c":"6.37\tResource:","t":"Str"},{"t":"Space"},{"c":"snapshots/{snapshotId}","t":"Str"}],["#tabresource-snapshotssnapshotid",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-95",[],[]],[{"c":"6.37.1\tDescription","t":"Str"}],["#tabdescription-95",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-33",[],[]],[{"c":"6.37.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-33",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-33",[],[]],[{"c":"6.37.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-33",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabget-20",[],[]],[{"c":"6.37.3.1\tGET","t":"Str"}],["#tabget-20",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabpatch-8",[],[]],[{"c":"6.37.3.2\tPATCH","t":"Str"}],["#tabpatch-8",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabdelete-12",[],[]],[{"c":"6.37.3.3\tDELETE","t":"Str"}],["#tabdelete-12",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabresource-snapshotssnapshotidclone",[],[]],[{"c":"6.38\tResource:","t":"Str"},{"t":"Space"},{"c":"snapshots/{snapshotId}/clone","t":"Str"}],["#tabresource-snapshotssnapshotidclone",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabdescription-96",[],[]],[{"c":"6.38.1\tDescription","t":"Str"}],["#tabdescription-96",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-definition-34",[],[]],[{"c":"6.38.2\tResource","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#tabresource-definition-34",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabresource-methods-34",[],[]],[{"c":"6.38.3\tResource","t":"Str"},{"t":"Space"},{"c":"methods","t":"Str"}],["#tabresource-methods-34",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabpost-18",[],[]],[{"c":"6.38.3.1\tPOST","t":"Str"}],["#tabpost-18",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-tabapi-mqtt-notification-binding",[],[]],[{"c":"7\tAPI","t":"Str"},{"t":"Space"},{"c":"MQTT","t":"Str"},{"t":"Space"},{"c":"Notification","t":"Str"},{"t":"Space"},{"c":"Binding","t":"Str"}],["#tabapi-mqtt-notification-binding",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-tabintroduction-23",[],[]],[{"c":"7.1\tIntroduction","t":"Str"}],["#tabintroduction-23",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-tabnotification-behaviour-3",[],[]],[{"c":"7.2\tNotification","t":"Str"},{"t":"Space"},{"c":"behaviour","t":"Str"}],["#tabnotification-behaviour-3",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-a-normative-ngsi-ld-identifier-considerations",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"A","t":"Str"},{"t":"Space"},{"c":"(normative):","t":"Str"},{"t":"LineBreak"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"identifier","t":"Str"},{"t":"Space"},{"c":"considerations","t":"Str"}],["#annex-a-normative-ngsi-ld-identifier-considerations",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-a.1tabintroduction",[],[]],[{"c":"A.1\tIntroduction","t":"Str"}],["#a.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-a.2tabentity-identifiers",[],[]],[{"c":"A.2\tEntity","t":"Str"},{"t":"Space"},{"c":"identifiers","t":"Str"}],["#a.2tabentity-identifiers",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-a.3tabngsi-ld-namespace",[],[]],[{"c":"A.3\tNGSI-LD","t":"Str"},{"t":"Space"},{"c":"namespace","t":"Str"}],["#a.3tabngsi-ld-namespace",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-b-normative-core-ngsi-ld-context-definition",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"B","t":"Str"},{"t":"Space"},{"c":"(normative):","t":"Str"},{"t":"LineBreak"},{"c":"Core","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"@context","t":"Str"},{"t":"Space"},{"c":"definition","t":"Str"}],["#annex-b-normative-core-ngsi-ld-context-definition",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-annex-c-informative-examples-of-using-the-api",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"C","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Examples","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"using","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"API","t":"Str"}],["#annex-c-informative-examples-of-using-the-api",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.1tabintroduction",[],[]],[{"c":"C.1\tIntroduction","t":"Str"}],["#c.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.2tabentity-representation",[],[]],[{"c":"C.2\tEntity","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#c.2tabentity-representation",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.2.1tabproperty-graph",[],[]],[{"c":"C.2.1\tProperty","t":"Str"},{"t":"Space"},{"c":"Graph","t":"Str"}],["#c.2.1tabproperty-graph",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.2.2tabvehicle-entity",[],[]],[{"c":"C.2.2\tVehicle","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#c.2.2tabvehicle-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.2.3tabparking-entity",[],[]],[{"c":"C.2.3\tParking","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"}],["#c.2.3tabparking-entity",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.2.4tabcontext",[],[]],[{"c":"C.2.4\t@context","t":"Str"}],["#c.2.4tabcontext",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.3tabcontext-source-registration",[],[]],[{"c":"C.3\tContext","t":"Str"},{"t":"Space"},{"c":"Source","t":"Str"},{"t":"Space"},{"c":"Registration","t":"Str"}],["#c.3tabcontext-source-registration",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.4tabcontext-subscription",[],[]],[{"c":"C.4\tContext","t":"Str"},{"t":"Space"},{"c":"Subscription","t":"Str"}],["#c.4tabcontext-subscription",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5tabhttp-rest-api-examples",[],[]],[{"c":"C.5\tHTTP","t":"Str"},{"t":"Space"},{"c":"REST","t":"Str"},{"t":"Space"},{"c":"API","t":"Str"},{"t":"Space"},{"c":"Examples","t":"Str"}],["#c.5tabhttp-rest-api-examples",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.1tabintroduction",[],[]],[{"c":"C.5.1\tIntroduction","t":"Str"}],["#c.5.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.2tabcreate-entity-of-type-vehicle",[],[]],[{"c":"C.5.2\tCreate","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"Vehicle","t":"Str"}],["#c.5.2tabcreate-entity-of-type-vehicle",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.2.1tabhttp-request",[],[]],[{"c":"C.5.2.1\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.2.1tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.2.2tabhttp-response",[],[]],[{"c":"C.5.2.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.2.2tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.3tabquery-entities",[],[]],[{"c":"C.5.3\tQuery","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"}],["#c.5.3tabquery-entities",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.3.1tabintroduction",[],[]],[{"c":"C.5.3.1\tIntroduction","t":"Str"}],["#c.5.3.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.3.2tabhttp-request",[],[]],[{"c":"C.5.3.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.3.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.3.3tabhttp-response",[],[]],[{"c":"C.5.3.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.3.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.4tabquery-entities-pagination",[],[]],[{"c":"C.5.4\tQuery","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"},{"t":"Space"},{"c":"(Pagination)","t":"Str"}],["#c.5.4tabquery-entities-pagination",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.4.1tabintroduction",[],[]],[{"c":"C.5.4.1\tIntroduction","t":"Str"}],["#c.5.4.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.4.2tabhttp-request",[],[]],[{"c":"C.5.4.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.4.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.4.3tabhttp-response",[],[]],[{"c":"C.5.4.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.4.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.5tabtemporal-query",[],[]],[{"c":"C.5.5\tTemporal","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"}],["#c.5.5tabtemporal-query",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.5.1tabintroduction",[],[]],[{"c":"C.5.5.1\tIntroduction","t":"Str"}],["#c.5.5.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.5.2tabhttp-request-1",[],[]],[{"c":"C.5.5.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"},{"t":"Space"},{"c":"#1","t":"Str"}],["#c.5.5.2tabhttp-request-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.5.3tabhttp-response-1",[],[]],[{"c":"C.5.5.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"},{"t":"Space"},{"c":"#1","t":"Str"}],["#c.5.5.3tabhttp-response-1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.5.3tabhttp-request-2",[],[]],[{"c":"C.5.5.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"},{"t":"Space"},{"c":"#2","t":"Str"}],["#c.5.5.3tabhttp-request-2",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.5.4tabhttp-response-2",[],[]],[{"c":"C.5.5.4\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"},{"t":"Space"},{"c":"#2","t":"Str"}],["#c.5.5.4tabhttp-response-2",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.6tabtemporal-query-simplified-representation",[],[]],[{"c":"C.5.6\tTemporal","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"(Simplified","t":"Str"},{"t":"Space"},{"c":"Representation)","t":"Str"}],["#c.5.6tabtemporal-query-simplified-representation",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.6.1tabintroduction",[],[]],[{"c":"C.5.6.1\tIntroduction","t":"Str"}],["#c.5.6.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.6.2tabhttp-request",[],[]],[{"c":"C.5.6.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.6.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.6.3tabhttp-response",[],[]],[{"c":"C.5.6.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.6.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.7tabretrieve-available-entity-types",[],[]],[{"c":"C.5.7\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#c.5.7tabretrieve-available-entity-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.7.1tabintroduction",[],[]],[{"c":"C.5.7.1\tIntroduction","t":"Str"}],["#c.5.7.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.7.2tabhttp-request",[],[]],[{"c":"C.5.7.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.7.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.7.3tabhttp-response",[],[]],[{"c":"C.5.7.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.7.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.8tabretrieve-details-of-available-entity-types",[],[]],[{"c":"C.5.8\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Details","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Types","t":"Str"}],["#c.5.8tabretrieve-details-of-available-entity-types",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.8.1tabintroduction",[],[]],[{"c":"C.5.8.1\tIntroduction","t":"Str"}],["#c.5.8.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.8.2tabhttp-request",[],[]],[{"c":"C.5.8.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.8.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.8.3tabhttp-response",[],[]],[{"c":"C.5.8.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.8.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.9tabretrieve-available-entity-type-information",[],[]],[{"c":"C.5.9\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"Type","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#c.5.9tabretrieve-available-entity-type-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.9.1tabintroduction",[],[]],[{"c":"C.5.9.1\tIntroduction","t":"Str"}],["#c.5.9.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.9.2tabhttp-request",[],[]],[{"c":"C.5.9.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.9.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.9.3tabhttp-response",[],[]],[{"c":"C.5.9.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.9.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.10tabretrieve-available-attributes",[],[]],[{"c":"C.5.10\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#c.5.10tabretrieve-available-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.10.1tabintroduction",[],[]],[{"c":"C.5.10.1\tIntroduction","t":"Str"}],["#c.5.10.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.10.2tabhttp-request",[],[]],[{"c":"C.5.10.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.10.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.10.3tabhttp-response",[],[]],[{"c":"C.5.10.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.10.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.11tabretrieve-details-of-available-attributes",[],[]],[{"c":"C.5.11\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Details","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attributes","t":"Str"}],["#c.5.11tabretrieve-details-of-available-attributes",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.11.1tabintroduction",[],[]],[{"c":"C.5.11.1\tIntroduction","t":"Str"}],["#c.5.11.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.11.2tabhttp-request",[],[]],[{"c":"C.5.11.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.11.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.11.3tabhttp-response",[],[]],[{"c":"C.5.11.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.11.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.12tabretrieve-available-attribute-information",[],[]],[{"c":"C.5.12\tRetrieve","t":"Str"},{"t":"Space"},{"c":"Available","t":"Str"},{"t":"Space"},{"c":"Attribute","t":"Str"},{"t":"Space"},{"c":"Information","t":"Str"}],["#c.5.12tabretrieve-available-attribute-information",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.12.1tabintroduction",[],[]],[{"c":"C.5.12.1\tIntroduction","t":"Str"}],["#c.5.12.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.12.2tabhttp-request",[],[]],[{"c":"C.5.12.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.12.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.12.3tabhttp-response",[],[]],[{"c":"C.5.12.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.12.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.13tabquery-entities-natural-language-filtering",[],[]],[{"c":"C.5.13\tQuery","t":"Str"},{"t":"Space"},{"c":"Entities","t":"Str"},{"t":"Space"},{"c":"(Natural","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"},{"t":"Space"},{"c":"Filtering)","t":"Str"}],["#c.5.13tabquery-entities-natural-language-filtering",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.13.1tabintroduction",[],[]],[{"c":"C.5.13.1\tIntroduction","t":"Str"}],["#c.5.13.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.13.2tabhttp-request",[],[]],[{"c":"C.5.13.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.13.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.13.3tabhttp-response",[],[]],[{"c":"C.5.13.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.13.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.14tabtemporal-query-aggregated-representation",[],[]],[{"c":"C.5.14\tTemporal","t":"Str"},{"t":"Space"},{"c":"Query","t":"Str"},{"t":"Space"},{"c":"(Aggregated","t":"Str"},{"t":"Space"},{"c":"Representation)","t":"Str"}],["#c.5.14tabtemporal-query-aggregated-representation",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.14.1tabintroduction",[],[]],[{"c":"C.5.14.1\tIntroduction","t":"Str"}],["#c.5.14.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.14.2tabhttp-request",[],[]],[{"c":"C.5.14.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.14.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.14.3tabhttp-response",[],[]],[{"c":"C.5.14.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.14.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.15tabscope-queries",[],[]],[{"c":"C.5.15\tScope","t":"Str"},{"t":"Space"},{"c":"Queries","t":"Str"}],["#c.5.15tabscope-queries",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.15.1tabintroduction",[],[]],[{"c":"C.5.15.1\tIntroduction","t":"Str"}],["#c.5.15.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.15.2tabhttp-request",[],[]],[{"c":"C.5.15.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.15.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.15.3tabhttp-response",[],[]],[{"c":"C.5.15.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.15.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.5.16tabtemporal-scope-queries",[],[]],[{"c":"C.5.16\tTemporal","t":"Str"},{"t":"Space"},{"c":"Scope","t":"Str"},{"t":"Space"},{"c":"Queries","t":"Str"}],["#c.5.16tabtemporal-scope-queries",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-c.5.16.1tabintroduction",[],[]],[{"c":"C.5.16.1\tIntroduction","t":"Str"}],["#c.5.16.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.16.2tabhttp-request",[],[]],[{"c":"C.5.16.2\tHTTP","t":"Str"},{"t":"Space"},{"c":"Request","t":"Str"}],["#c.5.16.2tabhttp-request",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.5.16.3tabhttp-response",[],[]],[{"c":"C.5.16.3\tHTTP","t":"Str"},{"t":"Space"},{"c":"Response","t":"Str"}],["#c.5.16.3tabhttp-response",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-c.6tabdate-representation",[],[]],[{"c":"C.6\tDate","t":"Str"},{"t":"Space"},{"c":"Representation","t":"Str"}],["#c.6tabdate-representation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.7tabcontext-utilization-clarifications",[],[]],[{"c":"C.7\t@context","t":"Str"},{"t":"Space"},{"c":"utilization","t":"Str"},{"t":"Space"},{"c":"clarifications","t":"Str"}],["#c.7tabcontext-utilization-clarifications",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.8tablink-header-utilization-clarifications",[],[]],[{"c":"C.8\tLink","t":"Str"},{"t":"Space"},{"c":"header","t":"Str"},{"t":"Space"},{"c":"utilization","t":"Str"},{"t":"Space"},{"c":"clarifications","t":"Str"}],["#c.8tablink-header-utilization-clarifications",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.9tabcontext-processing-clarifications",[],[]],[{"c":"C.9\t@context","t":"Str"},{"t":"Space"},{"c":"processing","t":"Str"},{"t":"Space"},{"c":"clarifications","t":"Str"}],["#c.9tabcontext-processing-clarifications",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.10tabvaluetype-datatype-utilization-clarifications",[],[]],[{"c":"C.10\tValueType","t":"Str"},{"t":"Space"},{"c":"datatype","t":"Str"},{"t":"Space"},{"c":"utilization","t":"Str"},{"t":"Space"},{"c":"clarifications","t":"Str"}],["#c.10tabvaluetype-datatype-utilization-clarifications",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-c.11tabentity-with-digital-signature-for-a-property",[],[]],[{"c":"C.11\tEntity","t":"Str"},{"t":"Space"},{"c":"with","t":"Str"},{"t":"Space"},{"c":"digital","t":"Str"},{"t":"Space"},{"c":"signature","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"}],["#c.11tabentity-with-digital-signature-for-a-property",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-d-informative-transformation-algorithms",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"D","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Transformation","t":"Str"},{"t":"Space"},{"c":"Algorithms","t":"Str"}],["#annex-d-informative-transformation-algorithms",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-d.1tabintroduction",[],[]],[{"c":"D.1\tIntroduction","t":"Str"}],["#d.1tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1",[],[]],[{"c":"D.2\tAlgorithm","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"transforming","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"into","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"JSON-LD","t":"Str"},{"t":"Space"},{"c":"document","t":"Str"},{"t":"Space"},{"c":"(ALG1)","t":"Str"}],["#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1",[],[]],[{"c":"D.3\tAlgorithm","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"transforming","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"},{"t":"Space"},{"c":"into","t":"Str"},{"t":"Space"},{"c":"JSON-LD","t":"Str"},{"t":"Space"},{"c":"(ALG1.1)","t":"Str"}],["#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2",[],[]],[{"c":"D.4\tAlgorithm","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"transforming","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"Relationship","t":"Str"},{"t":"Space"},{"c":"into","t":"Str"},{"t":"Space"},{"c":"JSON-LD","t":"Str"},{"t":"Space"},{"c":"(ALG1.2)","t":"Str"}],["#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"E","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"RDF-compatible","t":"Str"},{"t":"Space"},{"c":"specification","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"NGSI-LD","t":"Str"},{"t":"Space"},{"c":"meta-model","t":"Str"}],["#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-annex-f-informative-conventions-and-syntax-guidelines",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"F","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Conventions","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"syntax","t":"Str"},{"t":"Space"},{"c":"guidelines","t":"Str"}],["#annex-f-informative-conventions-and-syntax-guidelines",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-annex-g-informative-localization-and-internationalization-support",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"G","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Localization","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"Internationalization","t":"Str"},{"t":"Space"},{"c":"Support","t":"Str"}],["#annex-g-informative-localization-and-internationalization-support",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-g.0tabforeword",[],[]],[{"c":"G.0\tForeword","t":"Str"}],["#g.0tabforeword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.1tabintroduction",[],[]],[{"c":"G.1\tIntroduction","t":"Str"}],["#g.1tabintroduction",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-g.1.0tabforeword",[],[]],[{"c":"G.1.0\tForeword","t":"Str"}],["#g.1.0tabforeword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.1.1tabassociating-an-entity-with-a-natural-language",[],[]],[{"c":"G.1.1\tAssociating","t":"Str"},{"t":"Space"},{"c":"an","t":"Str"},{"t":"Space"},{"c":"Entity","t":"Str"},{"t":"Space"},{"c":"with","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Natural","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#g.1.1tabassociating-an-entity-with-a-natural-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.1.2tabassociating-a-property-with-a-natural-language",[],[]],[{"c":"G.1.2\tAssociating","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Property","t":"Str"},{"t":"Space"},{"c":"with","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"Natural","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"}],["#g.1.2tabassociating-a-property-with-a-natural-language",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.1.3tabassociating-as-equivalent-entity",[],[]],[{"c":"G.1.3\tAssociating","t":"Str"},{"t":"Space"},{"c":"as","t":"Str"},{"t":"Space"},{"c":"equivalent","t":"Str"},{"t":"Space"},{"c":"entity","t":"Str"}],["#g.1.3tabassociating-as-equivalent-entity",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-g.2tabnatural-language-collation-support",[],[]],[{"c":"G.2\tNatural","t":"Str"},{"t":"Space"},{"c":"Language","t":"Str"},{"t":"Space"},{"c":"Collation","t":"Str"},{"t":"Space"},{"c":"Support","t":"Str"}],["#g.2tabnatural-language-collation-support",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-g.2.0tabforeword",[],[]],[{"c":"G.2.0\tForeword","t":"Str"}],["#g.2.0tabforeword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.2.1tabmaintain-collations-as-metadata",[],[]],[{"c":"G.2.1\tMaintain","t":"Str"},{"t":"Space"},{"c":"collations","t":"Str"},{"t":"Space"},{"c":"as","t":"Str"},{"t":"Space"},{"c":"metadata","t":"Str"}],["#g.2.1tabmaintain-collations-as-metadata",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.2.2tabroute-language-sensitive-queries-via-a-proxy",[],[]],[{"c":"G.2.2\tRoute","t":"Str"},{"t":"Space"},{"c":"language","t":"Str"},{"t":"Space"},{"c":"sensitive","t":"Str"},{"t":"Space"},{"c":"queries","t":"Str"},{"t":"Space"},{"c":"via","t":"Str"},{"t":"Space"},{"c":"a","t":"Str"},{"t":"Space"},{"c":"proxy","t":"Str"}],["#g.2.2tabroute-language-sensitive-queries-via-a-proxy",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-g.3tablocalization-of-dates-currency-formats-etc.",[],[]],[{"c":"G.3\tLocalization","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Dates,","t":"Str"},{"t":"Space"},{"c":"Currency","t":"Str"},{"t":"Space"},{"c":"formats,","t":"Str"},{"t":"Space"},{"c":"etc.","t":"Str"}],["#g.3tablocalization-of-dates-currency-formats-etc.",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-g.3.0tabforeword",[],[]],[{"c":"G.3.0\tForeword","t":"Str"}],["#g.3.0tabforeword",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-g.3.1tablocalizing-dates",[],[]],[{"c":"G.3.1\tLocalizing","t":"Str"},{"t":"Space"},{"c":"Dates","t":"Str"}],["#g.3.1tablocalizing-dates",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-h-informative-suggested-actuation-workflows",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"H","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Suggested","t":"Str"},{"t":"Space"},{"c":"actuation","t":"Str"},{"t":"Space"},{"c":"workflows","t":"Str"}],["#annex-h-informative-suggested-actuation-workflows",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-h.1tabactuators-and-feedback-to-the-consumer",[],[]],[{"c":"H.1\tActuators","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"feedback","t":"Str"},{"t":"Space"},{"c":"to","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"consumer","t":"Str"}],["#h.1tabactuators-and-feedback-to-the-consumer",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.2tabarchitecture-for-actuation",[],[]],[{"c":"H.2\tArchitecture","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"actuation","t":"Str"}],["#h.2tabarchitecture-for-actuation",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.3tabstructure-of-commands-and-additional-properties",[],[]],[{"c":"H.3\tStructure","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"Commands","t":"Str"},{"t":"Space"},{"c":"and","t":"Str"},{"t":"Space"},{"c":"additional","t":"Str"},{"t":"Space"},{"c":"Properties","t":"Str"}],["#h.3tabstructure-of-commands-and-additional-properties",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-h.3.0tabintroduction",[],[]],[{"c":"H.3.0\tIntroduction","t":"Str"}],["#h.3.0tabintroduction",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.3.1tabproperty-for-listing-available-commands",[],[]],[{"c":"H.3.1\tProperty","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"listing","t":"Str"},{"t":"Space"},{"c":"available","t":"Str"},{"t":"Space"},{"c":"commands","t":"Str"}],["#h.3.1tabproperty-for-listing-available-commands",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.3.2tabproperties-for-command-endpoints",[],[]],[{"c":"H.3.2\tProperties","t":"Str"},{"t":"Space"},{"c":"for","t":"Str"},{"t":"Space"},{"c":"command","t":"Str"},{"t":"Space"},{"c":"endpoints","t":"Str"}],["#h.3.2tabproperties-for-command-endpoints",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-h.4tabcommunication-model",[],[]],[{"c":"H.4\tCommunication","t":"Str"},{"t":"Space"},{"c":"model","t":"Str"}],["#h.4tabcommunication-model",""]],"t":"Link"}],"t":"Plain"},{"c":[[{"c":[{"c":[["toc-h.4.1tabpossible-communication-models",[],[]],[{"c":"H.4.1\tPossible","t":"Str"},{"t":"Space"},{"c":"communication","t":"Str"},{"t":"Space"},{"c":"models","t":"Str"}],["#h.4.1tabpossible-communication-models",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.4.2tabsubscriptionnotification-model",[],[]],[{"c":"H.4.2\tSubscription/notification","t":"Str"},{"t":"Space"},{"c":"model","t":"Str"}],["#h.4.2tabsubscriptionnotification-model",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.4.3tabforwarding-model",[],[]],[{"c":"H.4.3\tForwarding","t":"Str"},{"t":"Space"},{"c":"model","t":"Str"}],["#h.4.3tabforwarding-model",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-h.5tabimplementation-of-the-subscription-based-actuation-workflow",[],[]],[{"c":"H.5\tImplementation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"subscription-based","t":"Str"},{"t":"Space"},{"c":"actuation","t":"Str"},{"t":"Space"},{"c":"workflow","t":"Str"}],["#h.5tabimplementation-of-the-subscription-based-actuation-workflow",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-h.6tabimplementation-of-the-registration-based-actuation-workflow",[],[]],[{"c":"H.6\tImplementation","t":"Str"},{"t":"Space"},{"c":"of","t":"Str"},{"t":"Space"},{"c":"the","t":"Str"},{"t":"Space"},{"c":"registration-based","t":"Str"},{"t":"Space"},{"c":"actuation","t":"Str"},{"t":"Space"},{"c":"workflow","t":"Str"}],["#h.6tabimplementation-of-the-registration-based-actuation-workflow",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"}],[{"c":[{"c":[["toc-annex-i-informative-change-history",[],[]],[{"c":"Annex","t":"Str"},{"t":"Space"},{"c":"I","t":"Str"},{"t":"Space"},{"c":"(informative):","t":"Str"},{"t":"LineBreak"},{"c":"Change","t":"Str"},{"t":"Space"},{"c":"history","t":"Str"}],["#annex-i-informative-change-history",""]],"t":"Link"}],"t":"Plain"}],[{"c":[{"c":[["toc-history",[],[]],[{"c":"History","t":"Str"}],["#history",""]],"t":"Link"}],"t":"Plain"}]],"t":"BulletList"} \ No newline at end of file diff --git a/API/sitemap.json b/API/sitemap.json deleted file mode 100644 index cd2642819b0b25286c709e7bcc8ee88c93f50238..0000000000000000000000000000000000000000 --- a/API/sitemap.json +++ /dev/null @@ -1 +0,0 @@ -{"section":{"id":"","level":"0","number":null,"path":"index.html","title":""},"subsections":[{"section":{"id":"intellectual-property-rights","level":"1","number":"1","path":"1-intellectual-property-rights.html#intellectual-property-rights","title":"Intellectual Property Rights"},"subsections":[]},{"section":{"id":"foreword","level":"1","number":"2","path":"2-foreword.html#foreword","title":"Foreword"},"subsections":[]},{"section":{"id":"modal-verbs-terminology","level":"1","number":"3","path":"3-modal-verbs-terminology.html#modal-verbs-terminology","title":"Modal verbs terminology"},"subsections":[]},{"section":{"id":"executive-summary","level":"1","number":"4","path":"4-executive-summary.html#executive-summary","title":"Executive summary"},"subsections":[]},{"section":{"id":"introduction","level":"1","number":"5","path":"5-introduction.html#introduction","title":"Introduction"},"subsections":[]},{"section":{"id":"tabscope","level":"1","number":"6","path":"6-tabscope.html#tabscope","title":"1 Scope"},"subsections":[]},{"section":{"id":"tabreferences","level":"1","number":"7","path":"7-tabreferences.html#tabreferences","title":"2 References"},"subsections":[{"section":{"id":"tabnormative-references","level":"2","number":"7.1","path":"7-tabreferences.html#tabnormative-references","title":"2.1 Normative references"},"subsections":[]},{"section":{"id":"tabinformative-references","level":"2","number":"7.2","path":"7-tabreferences.html#tabinformative-references","title":"2.2 Informative references"},"subsections":[]}]},{"section":{"id":"tabdefinition-of-terms-symbols-and-abbreviations","level":"1","number":"8","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabdefinition-of-terms-symbols-and-abbreviations","title":"3 Definition of terms, symbols and abbreviations"},"subsections":[{"section":{"id":"tabterms","level":"2","number":"8.1","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabterms","title":"3.1 Terms"},"subsections":[]},{"section":{"id":"tabsymbols","level":"2","number":"8.2","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabsymbols","title":"3.2 Symbols"},"subsections":[]},{"section":{"id":"tababbreviations","level":"2","number":"8.3","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tababbreviations","title":"3.3 Abbreviations"},"subsections":[]}]},{"section":{"id":"tabcontext-information-management-framework","level":"1","number":"9","path":"9-tabcontext-information-management-framework.html#tabcontext-information-management-framework","title":"4 Context Information Management Framework"},"subsections":[{"section":{"id":"tabintroduction","level":"2","number":"9.1","path":"9-tabcontext-information-management-framework.html#tabintroduction","title":"4.1 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-information-model","level":"2","number":"9.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-information-model","title":"4.2 NGSI-LD Information Model"},"subsections":[{"section":{"id":"tabintroduction-1","level":"3","number":"9.2.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-1","title":"4.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-meta-model","level":"3","number":"9.2.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-meta-model","title":"4.2.2 NGSI-LD Meta Model"},"subsections":[]},{"section":{"id":"tabcross-domain-ontology","level":"3","number":"9.2.3","path":"9-tabcontext-information-management-framework.html#tabcross-domain-ontology","title":"4.2.3 Cross Domain Ontology"},"subsections":[]},{"section":{"id":"tabngsi-ld-domain-specific-models-and-instantiation","level":"3","number":"9.2.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-domain-specific-models-and-instantiation","title":"4.2.4 NGSI-LD domain-specific models and instantiation"},"subsections":[]},{"section":{"id":"tabuml-representation","level":"3","number":"9.2.5","path":"9-tabcontext-information-management-framework.html#tabuml-representation","title":"4.2.5 UML representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-architectural-considerations","level":"2","number":"9.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-architectural-considerations","title":"4.3 NGSI-LD Architectural Considerations"},"subsections":[{"section":{"id":"tabintroduction-2","level":"3","number":"9.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-2","title":"4.3.1 Introduction"},"subsections":[]},{"section":{"id":"tabcentralized-architecture","level":"3","number":"9.3.2","path":"9-tabcontext-information-management-framework.html#tabcentralized-architecture","title":"4.3.2 Centralized architecture"},"subsections":[]},{"section":{"id":"tabdistributed-architecture","level":"3","number":"9.3.3","path":"9-tabcontext-information-management-framework.html#tabdistributed-architecture","title":"4.3.3 Distributed architecture"},"subsections":[]},{"section":{"id":"tabfederated-architecture","level":"3","number":"9.3.4","path":"9-tabcontext-information-management-framework.html#tabfederated-architecture","title":"4.3.4 Federated architecture"},"subsections":[]},{"section":{"id":"tabngsi-ld-api-structure-and-implementation-options","level":"3","number":"9.3.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-api-structure-and-implementation-options","title":"4.3.5 NGSI-LD API Structure and Implementation Options"},"subsections":[]},{"section":{"id":"tabdistributed-operations","level":"3","number":"9.3.6","path":"9-tabcontext-information-management-framework.html#tabdistributed-operations","title":"4.3.6 Distributed Operations"},"subsections":[{"section":{"id":"tabintroduction-3","level":"4","number":"9.3.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-3","title":"4.3.6.1 Introduction"},"subsections":[]},{"section":{"id":"tabadditive-registrations","level":"4","number":"9.3.6.2","path":"9-tabcontext-information-management-framework.html#tabadditive-registrations","title":"4.3.6.2 Additive Registrations"},"subsections":[]},{"section":{"id":"tabproxied-registrations","level":"4","number":"9.3.6.3","path":"9-tabcontext-information-management-framework.html#tabproxied-registrations","title":"4.3.6.3 Proxied Registrations"},"subsections":[]},{"section":{"id":"tablimiting-cascading-distributed-operations","level":"4","number":"9.3.6.4","path":"9-tabcontext-information-management-framework.html#tablimiting-cascading-distributed-operations","title":"4.3.6.4 Limiting Cascading Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source","level":"4","number":"9.3.6.5","path":"9-tabcontext-information-management-framework.html#tabextra-information-to-provide-when-contacting-context-source","title":"4.3.6.5 Extra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","level":"4","number":"9.3.6.6","path":"9-tabcontext-information-management-framework.html#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","title":"4.3.6.6 Additional pre- and post-processing of extra information when contacting Context Source"},"subsections":[]},{"section":{"id":"tabquerying-and-retrieving-distributed-entities-as-unitary-operations","level":"4","number":"9.3.6.7","path":"9-tabcontext-information-management-framework.html#tabquerying-and-retrieving-distributed-entities-as-unitary-operations","title":"4.3.6.7 Querying and Retrieving Distributed Entities as Unitary Operations"},"subsections":[]},{"section":{"id":"tabbackwards-compatibility-of-context-source-payloads","level":"4","number":"9.3.6.8","path":"9-tabcontext-information-management-framework.html#tabbackwards-compatibility-of-context-source-payloads","title":"4.3.6.8 Backwards compatibility of Context Source payloads"},"subsections":[]}]},{"section":{"id":"tabsnapshots","level":"3","number":"9.3.7","path":"9-tabcontext-information-management-framework.html#tabsnapshots","title":"4.3.7 Snapshots"},"subsections":[]}]},{"section":{"id":"tabcore-and-user-ngsi-ld-context","level":"2","number":"9.4","path":"9-tabcontext-information-management-framework.html#tabcore-and-user-ngsi-ld-context","title":"4.4 Core and user NGSI-LD @context"},"subsections":[]},{"section":{"id":"tabngsi-ld-data-representation","level":"2","number":"9.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-data-representation","title":"4.5 NGSI-LD Data Representation"},"subsections":[{"section":{"id":"tabintroduction-4","level":"3","number":"9.5.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-4","title":"4.5.0 Introduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-representation","level":"3","number":"9.5.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-representation","title":"4.5.1 NGSI-LD Entity Representation"},"subsections":[]},{"section":{"id":"tabngsi-ld-property-representations","level":"3","number":"9.5.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-property-representations","title":"4.5.2 NGSI-LD Property Representations"},"subsections":[{"section":{"id":"tabintroduction-5","level":"4","number":"9.5.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-5","title":"4.5.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-property","level":"4","number":"9.5.3.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-property","title":"4.5.2.2 Normalized NGSI-LD Property"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-property","level":"4","number":"9.5.3.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-property","title":"4.5.2.3 Concise NGSI-LD Property"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-relationship-representations","level":"3","number":"9.5.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-relationship-representations","title":"4.5.3 NGSI-LD Relationship Representations"},"subsections":[{"section":{"id":"tabintroduction-6","level":"4","number":"9.5.4.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-6","title":"4.5.3.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-relationship","level":"4","number":"9.5.4.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-relationship","title":"4.5.3.2 Normalized NGSI-LD Relationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-relationship","level":"4","number":"9.5.4.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-relationship","title":"4.5.3.3 Concise NGSI-LD Relationship"},"subsections":[]}]},{"section":{"id":"tabsimplified-representation","level":"3","number":"9.5.5","path":"9-tabcontext-information-management-framework.html#tabsimplified-representation","title":"4.5.4 Simplified Representation"},"subsections":[]},{"section":{"id":"tabmulti-attribute-support","level":"3","number":"9.5.6","path":"9-tabcontext-information-management-framework.html#tabmulti-attribute-support","title":"4.5.5 Multi-Attribute Support"},"subsections":[{"section":{"id":"tabintroduction-7","level":"4","number":"9.5.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-7","title":"4.5.5.1 Introduction"},"subsections":[]},{"section":{"id":"tabprocessing-of-conflicting-transient-entities","level":"4","number":"9.5.6.2","path":"9-tabcontext-information-management-framework.html#tabprocessing-of-conflicting-transient-entities","title":"4.5.5.2 Processing of Conflicting Transient Entities"},"subsections":[]},{"section":{"id":"tabprocessing-of-conflicting-attributes","level":"4","number":"9.5.6.3","path":"9-tabcontext-information-management-framework.html#tabprocessing-of-conflicting-attributes","title":"4.5.5.3 Processing of Conflicting Attributes"},"subsections":[]}]},{"section":{"id":"tabtemporal-representation-of-an-entity","level":"3","number":"9.5.7","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-an-entity","title":"4.5.6 Temporal Representation of an Entity"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-property","level":"3","number":"9.5.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-property","title":"4.5.7 Temporal Representation of a Property"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-relationship","level":"3","number":"9.5.9","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-relationship","title":"4.5.8 Temporal Representation of a Relationship"},"subsections":[]},{"section":{"id":"tabsimplified-temporal-representation-of-an-entity","level":"3","number":"9.5.10","path":"9-tabcontext-information-management-framework.html#tabsimplified-temporal-representation-of-an-entity","title":"4.5.9 Simplified temporal representation of an Entity"},"subsections":[]},{"section":{"id":"tabentity-type-list-representation","level":"3","number":"9.5.11","path":"9-tabcontext-information-management-framework.html#tabentity-type-list-representation","title":"4.5.10 Entity Type List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-entity-type-list-representation","level":"3","number":"9.5.12","path":"9-tabcontext-information-management-framework.html#tabdetailed-entity-type-list-representation","title":"4.5.11 Detailed Entity Type List Representation"},"subsections":[]},{"section":{"id":"tabentity-type-information-representation","level":"3","number":"9.5.13","path":"9-tabcontext-information-management-framework.html#tabentity-type-information-representation","title":"4.5.12 Entity Type Information Representation"},"subsections":[]},{"section":{"id":"tabattribute-list-representation","level":"3","number":"9.5.14","path":"9-tabcontext-information-management-framework.html#tabattribute-list-representation","title":"4.5.13 Attribute List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-attribute-list-representation","level":"3","number":"9.5.15","path":"9-tabcontext-information-management-framework.html#tabdetailed-attribute-list-representation","title":"4.5.14 Detailed Attribute List Representation"},"subsections":[]},{"section":{"id":"tabattribute-information-representation","level":"3","number":"9.5.16","path":"9-tabcontext-information-management-framework.html#tabattribute-information-representation","title":"4.5.15 Attribute Information Representation"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-entities","level":"3","number":"9.5.17","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-entities","title":"4.5.16 GeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword","level":"4","number":"9.5.17.1","path":"9-tabcontext-information-management-framework.html#tabforeword","title":"4.5.16.0 Foreword"},"subsections":[]},{"section":{"id":"tabtop-level-geometry-field-selection-algorithm","level":"4","number":"9.5.17.2","path":"9-tabcontext-information-management-framework.html#tabtop-level-geometry-field-selection-algorithm","title":"4.5.16.1 Top-level “geometry” field selection algorithm"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-an-individual-entity","level":"4","number":"9.5.17.3","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-an-individual-entity","title":"4.5.16.2 GeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-multiple-entities","level":"4","number":"9.5.17.4","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-multiple-entities","title":"4.5.16.3 GeoJSON Representation of Multiple Entities"},"subsections":[]}]},{"section":{"id":"tabsimplified-geojson-representation-of-entities","level":"3","number":"9.5.18","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-entities","title":"4.5.17 Simplified GeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword-1","level":"4","number":"9.5.18.1","path":"9-tabcontext-information-management-framework.html#tabforeword-1","title":"4.5.17.0 Foreword"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-an-individual-entity","level":"4","number":"9.5.18.2","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-an-individual-entity","title":"4.5.17.1 Simplified GeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-multiple-entities","level":"4","number":"9.5.18.3","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-multiple-entities","title":"4.5.17.2 Simplified GeoJSON Representation of multiple Entities"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-languageproperty-representations","level":"3","number":"9.5.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-languageproperty-representations","title":"4.5.18 NGSI-LD LanguageProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-8","level":"4","number":"9.5.19.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-8","title":"4.5.18.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-languageproperty","level":"4","number":"9.5.19.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-languageproperty","title":"4.5.18.2 Normalized NGSI-LD LanguageProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-languageproperty","level":"4","number":"9.5.19.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-languageproperty","title":"4.5.18.3 Concise NGSI-LD LanguageProperty"},"subsections":[]}]},{"section":{"id":"tabaggregated-temporal-representation-of-an-entity","level":"3","number":"9.5.20","path":"9-tabcontext-information-management-framework.html#tabaggregated-temporal-representation-of-an-entity","title":"4.5.19 Aggregated temporal representation of an Entity"},"subsections":[{"section":{"id":"tabforeword-2","level":"4","number":"9.5.20.1","path":"9-tabcontext-information-management-framework.html#tabforeword-2","title":"4.5.19.0 Foreword"},"subsections":[]},{"section":{"id":"tabsupported-behaviours-for-aggregation-functions","level":"4","number":"9.5.20.2","path":"9-tabcontext-information-management-framework.html#tabsupported-behaviours-for-aggregation-functions","title":"4.5.19.1 Supported behaviours for aggregation functions"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-vocabproperty-representations","level":"3","number":"9.5.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-vocabproperty-representations","title":"4.5.20 NGSI-LD VocabProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-9","level":"4","number":"9.5.21.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-9","title":"4.5.20.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-vocabproperty","title":"4.5.20.2 Normalized NGSI-LD VocabProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-vocabproperty","title":"4.5.20.3 Concise NGSI-LD VocabProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listproperty-representations","level":"3","number":"9.5.22","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listproperty-representations","title":"4.5.21 NGSI-LD ListProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-10","level":"4","number":"9.5.22.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-10","title":"4.5.21.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listproperty","level":"4","number":"9.5.22.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listproperty","title":"4.5.21.2 Normalized NGSI-LD ListProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listproperty","level":"4","number":"9.5.22.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listproperty","title":"4.5.21.3 Concise NGSI-LD ListProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listrelationship-representations","level":"3","number":"9.5.23","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listrelationship-representations","title":"4.5.22 NGSI-LD ListRelationship Representations"},"subsections":[{"section":{"id":"tabintroduction-11","level":"4","number":"9.5.23.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-11","title":"4.5.22.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listrelationship","level":"4","number":"9.5.23.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listrelationship","title":"4.5.22.2 Normalized NGSI-LD ListRelationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listrelationship","level":"4","number":"9.5.23.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listrelationship","title":"4.5.22.3 Concise NGSI-LD ListRelationship"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-linked-entity-retrieval","level":"3","number":"9.5.24","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-linked-entity-retrieval","title":"4.5.23 NGSI-LD Linked Entity Retrieval"},"subsections":[{"section":{"id":"tabintroduction-12","level":"4","number":"9.5.24.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-12","title":"4.5.23.1 Introduction"},"subsections":[]},{"section":{"id":"tabinline-linked-entity-representation","level":"4","number":"9.5.24.2","path":"9-tabcontext-information-management-framework.html#tabinline-linked-entity-representation","title":"4.5.23.2 Inline Linked Entity Representation"},"subsections":[]},{"section":{"id":"tabflattened-linked-entity-representation","level":"4","number":"9.5.24.3","path":"9-tabcontext-information-management-framework.html#tabflattened-linked-entity-representation","title":"4.5.23.3 Flattened Linked Entity Representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-jsonproperty-representations","level":"3","number":"9.5.25","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-jsonproperty-representations","title":"4.5.24 NGSI-LD JsonProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-13","level":"4","number":"9.5.25.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-13","title":"4.5.24.1 Introduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-jsonproperty","title":"4.5.24.2 Normalized NGSI-LD JsonProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-jsonproperty","title":"4.5.24.3 Concise NGSI-LD JsonProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-entitymap-representation","level":"3","number":"9.5.26","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entitymap-representation","title":"4.5.25 NGSI-LD EntityMap Representation"},"subsections":[]}]},{"section":{"id":"tabdata-representation-restrictions","level":"2","number":"9.6","path":"9-tabcontext-information-management-framework.html#tabdata-representation-restrictions","title":"4.6 Data Representation Restrictions"},"subsections":[{"section":{"id":"tabsupported-text-encodings","level":"3","number":"9.6.1","path":"9-tabcontext-information-management-framework.html#tabsupported-text-encodings","title":"4.6.1 Supported text encodings"},"subsections":[]},{"section":{"id":"tabsupported-names","level":"3","number":"9.6.2","path":"9-tabcontext-information-management-framework.html#tabsupported-names","title":"4.6.2 Supported names"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-values","level":"3","number":"9.6.3","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-values","title":"4.6.3 Supported data types for Values"},"subsections":[]},{"section":{"id":"tabsupported-content","level":"3","number":"9.6.4","path":"9-tabcontext-information-management-framework.html#tabsupported-content","title":"4.6.4 Supported Content"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-languagemaps","level":"3","number":"9.6.5","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-languagemaps","title":"4.6.5 Supported data types for LanguageMaps"},"subsections":[]},{"section":{"id":"tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","level":"3","number":"9.6.6","path":"9-tabcontext-information-management-framework.html#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","title":"4.6.6 Ordering of Entities in arrays having more than one instance of the same Entity"},"subsections":[]}]},{"section":{"id":"tabgeospatial-properties","level":"2","number":"9.7","path":"9-tabcontext-information-management-framework.html#tabgeospatial-properties","title":"4.7 Geospatial Properties"},"subsections":[{"section":{"id":"tabgeojson-geometries","level":"3","number":"9.7.1","path":"9-tabcontext-information-management-framework.html#tabgeojson-geometries","title":"4.7.1 GeoJSON Geometries"},"subsections":[]},{"section":{"id":"tabrepresentation-of-geojson-geometries-in-json-ld","level":"3","number":"9.7.2","path":"9-tabcontext-information-management-framework.html#tabrepresentation-of-geojson-geometries-in-json-ld","title":"4.7.2 Representation of GeoJSON Geometries in JSON-LD"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-geoproperty","level":"3","number":"9.7.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-geoproperty","title":"4.7.3 Concise NGSI-LD GeoProperty"},"subsections":[]}]},{"section":{"id":"tabtemporal-properties","level":"2","number":"9.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-properties","title":"4.8 Temporal Properties"},"subsections":[]},{"section":{"id":"tabngsi-ld-query-language","level":"2","number":"9.9","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-query-language","title":"4.9 NGSI-LD Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-geoquery-language","level":"2","number":"9.10","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-geoquery-language","title":"4.10 NGSI-LD Geoquery Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-temporal-query-language","level":"2","number":"9.11","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-temporal-query-language","title":"4.11 NGSI-LD Temporal Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-pagination","level":"2","number":"9.12","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-pagination","title":"4.12 NGSI-LD Pagination"},"subsections":[]},{"section":{"id":"tabcounting-the-number-of-results","level":"2","number":"9.13","path":"9-tabcontext-information-management-framework.html#tabcounting-the-number-of-results","title":"4.13 Counting the Number of Results"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-tenants","level":"2","number":"9.14","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-tenants","title":"4.14 Supporting Multiple Tenants"},"subsections":[]},{"section":{"id":"tabngsi-ld-language-filter","level":"2","number":"9.15","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-language-filter","title":"4.15 NGSI-LD Language Filter"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-entity-types","level":"2","number":"9.16","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-entity-types","title":"4.16 Supporting Multiple Entity Types"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-type-selection-language","level":"2","number":"9.17","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-type-selection-language","title":"4.17 NGSI-LD Entity Type Selection Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-scopes","level":"2","number":"9.18","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scopes","title":"4.18 NGSI-LD Scopes"},"subsections":[]},{"section":{"id":"tabngsi-ld-scope-query-language","level":"2","number":"9.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scope-query-language","title":"4.19 NGSI-LD Scope Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-distributed-operation-names","level":"2","number":"9.20","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-distributed-operation-names","title":"4.20 NGSI-LD Distributed Operation names"},"subsections":[]},{"section":{"id":"tabngsi-ld-attribute-projection-language","level":"2","number":"9.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-attribute-projection-language","title":"4.21 NGSI-LD Attribute Projection Language"},"subsections":[]},{"section":{"id":"tabtransient-storage-of-entities-and-attributes","level":"2","number":"9.22","path":"9-tabcontext-information-management-framework.html#tabtransient-storage-of-entities-and-attributes","title":"4.22 Transient Storage of Entities and Attributes"},"subsections":[]},{"section":{"id":"tabentity-ordering","level":"2","number":"9.23","path":"9-tabcontext-information-management-framework.html#tabentity-ordering","title":"4.23 Entity Ordering"},"subsections":[{"section":{"id":"tabintroduction-14","level":"3","number":"9.23.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-14","title":"4.23.1 Introduction"},"subsections":[]},{"section":{"id":"tabdatatype-comparison-order","level":"3","number":"9.23.2","path":"9-tabcontext-information-management-framework.html#tabdatatype-comparison-order","title":"4.23.2 Datatype Comparison Order"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-ordering-language","level":"3","number":"9.23.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-ordering-language","title":"4.23.3 NGSI-LD Entity Ordering Language"},"subsections":[]}]}]},{"section":{"id":"tabapi-operation-definition","level":"1","number":"10","path":"10-tabapi-operation-definition.html#tabapi-operation-definition","title":"5 API Operation Definition"},"subsections":[{"section":{"id":"tabintroduction-15","level":"2","number":"10.1","path":"10-tabapi-operation-definition.html#tabintroduction-15","title":"5.1 Introduction"},"subsections":[]},{"section":{"id":"tabdata-types","level":"2","number":"10.2","path":"10-tabapi-operation-definition.html#tabdata-types","title":"5.2 Data Types"},"subsections":[{"section":{"id":"tabintroduction-16","level":"3","number":"10.2.1","path":"10-tabapi-operation-definition.html#tabintroduction-16","title":"5.2.1 Introduction"},"subsections":[]},{"section":{"id":"tabcommon-members","level":"3","number":"10.2.2","path":"10-tabapi-operation-definition.html#tabcommon-members","title":"5.2.2 Common members"},"subsections":[]},{"section":{"id":"tabcontext","level":"3","number":"10.2.3","path":"10-tabapi-operation-definition.html#tabcontext","title":"5.2.3 @context"},"subsections":[]},{"section":{"id":"tabentity","level":"3","number":"10.2.4","path":"10-tabapi-operation-definition.html#tabentity","title":"5.2.4 Entity"},"subsections":[]},{"section":{"id":"tabproperty","level":"3","number":"10.2.5","path":"10-tabapi-operation-definition.html#tabproperty","title":"5.2.5 Property"},"subsections":[]},{"section":{"id":"tabrelationship","level":"3","number":"10.2.6","path":"10-tabapi-operation-definition.html#tabrelationship","title":"5.2.6 Relationship"},"subsections":[]},{"section":{"id":"tabgeoproperty","level":"3","number":"10.2.7","path":"10-tabapi-operation-definition.html#tabgeoproperty","title":"5.2.7 GeoProperty"},"subsections":[]},{"section":{"id":"tabentityinfo","level":"3","number":"10.2.8","path":"10-tabapi-operation-definition.html#tabentityinfo","title":"5.2.8 EntityInfo"},"subsections":[]},{"section":{"id":"tabcsourceregistration","level":"3","number":"10.2.9","path":"10-tabapi-operation-definition.html#tabcsourceregistration","title":"5.2.9 CSourceRegistration"},"subsections":[]},{"section":{"id":"tabregistrationinfo","level":"3","number":"10.2.10","path":"10-tabapi-operation-definition.html#tabregistrationinfo","title":"5.2.10 RegistrationInfo"},"subsections":[]},{"section":{"id":"tabtimeinterval","level":"3","number":"10.2.11","path":"10-tabapi-operation-definition.html#tabtimeinterval","title":"5.2.11 TimeInterval"},"subsections":[]},{"section":{"id":"tabsubscription","level":"3","number":"10.2.12","path":"10-tabapi-operation-definition.html#tabsubscription","title":"5.2.12 Subscription"},"subsections":[]},{"section":{"id":"tabgeoquery","level":"3","number":"10.2.13","path":"10-tabapi-operation-definition.html#tabgeoquery","title":"5.2.13 GeoQuery"},"subsections":[]},{"section":{"id":"tabnotificationparams","level":"3","number":"10.2.14","path":"10-tabapi-operation-definition.html#tabnotificationparams","title":"5.2.14 NotificationParams"},"subsections":[{"section":{"id":"tabnotificationparams-data-type-definition","level":"4","number":"10.2.14.1","path":"10-tabapi-operation-definition.html#tabnotificationparams-data-type-definition","title":"5.2.14.1 NotificationParams data type definition"},"subsections":[]},{"section":{"id":"taboutput-only-members","level":"4","number":"10.2.14.2","path":"10-tabapi-operation-definition.html#taboutput-only-members","title":"5.2.14.2 Output only members"},"subsections":[]}]},{"section":{"id":"tabendpoint","level":"3","number":"10.2.15","path":"10-tabapi-operation-definition.html#tabendpoint","title":"5.2.15 Endpoint"},"subsections":[]},{"section":{"id":"tabbatchoperationresult","level":"3","number":"10.2.16","path":"10-tabapi-operation-definition.html#tabbatchoperationresult","title":"5.2.16 BatchOperationResult"},"subsections":[]},{"section":{"id":"tabbatchentityerror","level":"3","number":"10.2.17","path":"10-tabapi-operation-definition.html#tabbatchentityerror","title":"5.2.17 BatchEntityError"},"subsections":[]},{"section":{"id":"tabupdateresult","level":"3","number":"10.2.18","path":"10-tabapi-operation-definition.html#tabupdateresult","title":"5.2.18 UpdateResult"},"subsections":[]},{"section":{"id":"tabnotupdateddetails","level":"3","number":"10.2.19","path":"10-tabapi-operation-definition.html#tabnotupdateddetails","title":"5.2.19 NotUpdatedDetails"},"subsections":[]},{"section":{"id":"tabentitytemporal","level":"3","number":"10.2.20","path":"10-tabapi-operation-definition.html#tabentitytemporal","title":"5.2.20 EntityTemporal"},"subsections":[]},{"section":{"id":"tabtemporalquery","level":"3","number":"10.2.21","path":"10-tabapi-operation-definition.html#tabtemporalquery","title":"5.2.21 TemporalQuery"},"subsections":[]},{"section":{"id":"tabkeyvaluepair","level":"3","number":"10.2.22","path":"10-tabapi-operation-definition.html#tabkeyvaluepair","title":"5.2.22 KeyValuePair"},"subsections":[]},{"section":{"id":"tabquery","level":"3","number":"10.2.23","path":"10-tabapi-operation-definition.html#tabquery","title":"5.2.23 Query"},"subsections":[]},{"section":{"id":"tabentitytypelist","level":"3","number":"10.2.24","path":"10-tabapi-operation-definition.html#tabentitytypelist","title":"5.2.24 EntityTypeList"},"subsections":[]},{"section":{"id":"tabentitytype","level":"3","number":"10.2.25","path":"10-tabapi-operation-definition.html#tabentitytype","title":"5.2.25 EntityType"},"subsections":[]},{"section":{"id":"tabentitytypeinfo","level":"3","number":"10.2.26","path":"10-tabapi-operation-definition.html#tabentitytypeinfo","title":"5.2.26 EntityTypeInfo"},"subsections":[]},{"section":{"id":"tabattributelist","level":"3","number":"10.2.27","path":"10-tabapi-operation-definition.html#tabattributelist","title":"5.2.27 AttributeList"},"subsections":[]},{"section":{"id":"tabattribute","level":"3","number":"10.2.28","path":"10-tabapi-operation-definition.html#tabattribute","title":"5.2.28 Attribute"},"subsections":[]},{"section":{"id":"tabfeature","level":"3","number":"10.2.29","path":"10-tabapi-operation-definition.html#tabfeature","title":"5.2.29 Feature"},"subsections":[]},{"section":{"id":"tabfeaturecollection","level":"3","number":"10.2.30","path":"10-tabapi-operation-definition.html#tabfeaturecollection","title":"5.2.30 FeatureCollection"},"subsections":[]},{"section":{"id":"tabfeatureproperties","level":"3","number":"10.2.31","path":"10-tabapi-operation-definition.html#tabfeatureproperties","title":"5.2.31 FeatureProperties"},"subsections":[]},{"section":{"id":"tablanguageproperty","level":"3","number":"10.2.32","path":"10-tabapi-operation-definition.html#tablanguageproperty","title":"5.2.32 LanguageProperty"},"subsections":[]},{"section":{"id":"tabentityselector","level":"3","number":"10.2.33","path":"10-tabapi-operation-definition.html#tabentityselector","title":"5.2.33 EntitySelector"},"subsections":[]},{"section":{"id":"tabregistrationmanagementinfo","level":"3","number":"10.2.34","path":"10-tabapi-operation-definition.html#tabregistrationmanagementinfo","title":"5.2.34 RegistrationManagementInfo"},"subsections":[]},{"section":{"id":"tabvocabproperty","level":"3","number":"10.2.35","path":"10-tabapi-operation-definition.html#tabvocabproperty","title":"5.2.35 VocabProperty"},"subsections":[]},{"section":{"id":"tablistproperty","level":"3","number":"10.2.36","path":"10-tabapi-operation-definition.html#tablistproperty","title":"5.2.36 ListProperty"},"subsections":[]},{"section":{"id":"tablistrelationship","level":"3","number":"10.2.37","path":"10-tabapi-operation-definition.html#tablistrelationship","title":"5.2.37 ListRelationship"},"subsections":[]},{"section":{"id":"tabjsonproperty","level":"3","number":"10.2.38","path":"10-tabapi-operation-definition.html#tabjsonproperty","title":"5.2.38 JsonProperty"},"subsections":[]},{"section":{"id":"tabentitymap","level":"3","number":"10.2.39","path":"10-tabapi-operation-definition.html#tabentitymap","title":"5.2.39 EntityMap"},"subsections":[]},{"section":{"id":"tabcontext-source-identity","level":"3","number":"10.2.40","path":"10-tabapi-operation-definition.html#tabcontext-source-identity","title":"5.2.40 Context Source Identity"},"subsections":[]},{"section":{"id":"tabsnapshot","level":"3","number":"10.2.41","path":"10-tabapi-operation-definition.html#tabsnapshot","title":"5.2.41 Snapshot"},"subsections":[]},{"section":{"id":"tabexecutionresultdetails","level":"3","number":"10.2.42","path":"10-tabapi-operation-definition.html#tabexecutionresultdetails","title":"5.2.42 ExecutionResultDetails"},"subsections":[]},{"section":{"id":"taborderingparams","level":"3","number":"10.2.43","path":"10-tabapi-operation-definition.html#taborderingparams","title":"5.2.43 OrderingParams"},"subsections":[]},{"section":{"id":"tabaggregationparams","level":"3","number":"10.2.44","path":"10-tabapi-operation-definition.html#tabaggregationparams","title":"5.2.44 AggregationParams"},"subsections":[]}]},{"section":{"id":"tabnotification-data-types","level":"2","number":"10.3","path":"10-tabapi-operation-definition.html#tabnotification-data-types","title":"5.3 Notification data types"},"subsections":[{"section":{"id":"tabnotification","level":"3","number":"10.3.1","path":"10-tabapi-operation-definition.html#tabnotification","title":"5.3.1 Notification"},"subsections":[]},{"section":{"id":"tabcsourcenotification","level":"3","number":"10.3.2","path":"10-tabapi-operation-definition.html#tabcsourcenotification","title":"5.3.2 CSourceNotification"},"subsections":[]},{"section":{"id":"tabtriggerreasonenumeration","level":"3","number":"10.3.3","path":"10-tabapi-operation-definition.html#tabtriggerreasonenumeration","title":"5.3.3 TriggerReasonEnumeration"},"subsections":[]},{"section":{"id":"tabsnapshotnotification","level":"3","number":"10.3.4","path":"10-tabapi-operation-definition.html#tabsnapshotnotification","title":"5.3.4 SnapshotNotification"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-fragments","level":"2","number":"10.4","path":"10-tabapi-operation-definition.html#tabngsi-ld-fragments","title":"5.4 NGSI-LD Fragments"},"subsections":[]},{"section":{"id":"tabcommon-behaviours","level":"2","number":"10.5","path":"10-tabapi-operation-definition.html#tabcommon-behaviours","title":"5.5 Common Behaviours"},"subsections":[{"section":{"id":"tabintroduction-17","level":"3","number":"10.5.1","path":"10-tabapi-operation-definition.html#tabintroduction-17","title":"5.5.1 Introduction"},"subsections":[]},{"section":{"id":"taberror-types","level":"3","number":"10.5.2","path":"10-tabapi-operation-definition.html#taberror-types","title":"5.5.2 Error types"},"subsections":[]},{"section":{"id":"taberror-response-payload-body","level":"3","number":"10.5.3","path":"10-tabapi-operation-definition.html#taberror-response-payload-body","title":"5.5.3 Error response payload body"},"subsections":[]},{"section":{"id":"tabgeneral-ngsi-ld-validation","level":"3","number":"10.5.4","path":"10-tabapi-operation-definition.html#tabgeneral-ngsi-ld-validation","title":"5.5.4 General NGSI-LD validation"},"subsections":[]},{"section":{"id":"tabdefault-context-assignment","level":"3","number":"10.5.5","path":"10-tabapi-operation-definition.html#tabdefault-context-assignment","title":"5.5.5 Default @context assignment"},"subsections":[]},{"section":{"id":"taboperation-execution-and-generic-error-handling","level":"3","number":"10.5.6","path":"10-tabapi-operation-definition.html#taboperation-execution-and-generic-error-handling","title":"5.5.6 Operation execution and generic error handling"},"subsections":[]},{"section":{"id":"tabterm-to-uri-expansion-or-compaction","level":"3","number":"10.5.7","path":"10-tabapi-operation-definition.html#tabterm-to-uri-expansion-or-compaction","title":"5.5.7 Term to URI expansion or compaction"},"subsections":[]},{"section":{"id":"tabpartial-update-patch-behaviour","level":"3","number":"10.5.8","path":"10-tabapi-operation-definition.html#tabpartial-update-patch-behaviour","title":"5.5.8 Partial Update Patch Behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour","level":"3","number":"10.5.9","path":"10-tabapi-operation-definition.html#tabpagination-behaviour","title":"5.5.9 Pagination Behaviour"},"subsections":[{"section":{"id":"tabgeneral-pagination-behaviour","level":"4","number":"10.5.9.1","path":"10-tabapi-operation-definition.html#tabgeneral-pagination-behaviour","title":"5.5.9.1 General Pagination Behaviour"},"subsections":[]},{"section":{"id":"tabpagination-option-using-limit-and-offset","level":"4","number":"10.5.9.2","path":"10-tabapi-operation-definition.html#tabpagination-option-using-limit-and-offset","title":"5.5.9.2 Pagination option using limit and offset"},"subsections":[]},{"section":{"id":"tabpagination-with-entity-maps","level":"4","number":"10.5.9.3","path":"10-tabapi-operation-definition.html#tabpagination-with-entity-maps","title":"5.5.9.3 Pagination with Entity maps"},"subsections":[]}]},{"section":{"id":"tabmulti-tenant-behaviour","level":"3","number":"10.5.10","path":"10-tabapi-operation-definition.html#tabmulti-tenant-behaviour","title":"5.5.10 Multi-Tenant Behaviour"},"subsections":[]},{"section":{"id":"tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","level":"3","number":"10.5.11","path":"10-tabapi-operation-definition.html#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","title":"5.5.11 More than one instance of the same Entity in an Entity array"},"subsections":[{"section":{"id":"tabforeword-3","level":"4","number":"10.5.11.1","path":"10-tabapi-operation-definition.html#tabforeword-3","title":"5.5.11.0 Foreword"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-case","level":"4","number":"10.5.11.2","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-case","title":"5.5.11.1 Batch Entity Creation case"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert-case","level":"4","number":"10.5.11.3","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert-case","title":"5.5.11.2 Batch Entity Creation or Update (Upsert) case"},"subsections":[]},{"section":{"id":"tabbatch-entity-update-case","level":"4","number":"10.5.11.4","path":"10-tabapi-operation-definition.html#tabbatch-entity-update-case","title":"5.5.11.3 Batch Entity Update case"},"subsections":[]},{"section":{"id":"tabbatch-entity-delete-case","level":"4","number":"10.5.11.5","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete-case","title":"5.5.11.4 Batch Entity Delete case"},"subsections":[]},{"section":{"id":"tabbatch-entity-merge-case","level":"4","number":"10.5.11.6","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge-case","title":"5.5.11.5 Batch Entity Merge case"},"subsections":[]}]},{"section":{"id":"tabmerge-patch-behaviour","level":"3","number":"10.5.12","path":"10-tabapi-operation-definition.html#tabmerge-patch-behaviour","title":"5.5.12 Merge Patch Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-operations-to-local-scope","level":"3","number":"10.5.13","path":"10-tabapi-operation-definition.html#tablimiting-operations-to-local-scope","title":"5.5.13 Limiting operations to local scope"},"subsections":[]},{"section":{"id":"tabdistributed-transactional-behaviour","level":"3","number":"10.5.14","path":"10-tabapi-operation-definition.html#tabdistributed-transactional-behaviour","title":"5.5.14 Distributed Transactional Behaviour"},"subsections":[]},{"section":{"id":"tabsnapshot-behaviour","level":"3","number":"10.5.15","path":"10-tabapi-operation-definition.html#tabsnapshot-behaviour","title":"5.5.15 Snapshot Behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-information-provision","level":"2","number":"10.6","path":"10-tabapi-operation-definition.html#tabcontext-information-provision","title":"5.6 Context Information Provision"},"subsections":[{"section":{"id":"tabcreate-entity","level":"3","number":"10.6.1","path":"10-tabapi-operation-definition.html#tabcreate-entity","title":"5.6.1 Create Entity"},"subsections":[{"section":{"id":"tabdescription","level":"4","number":"10.6.1.1","path":"10-tabapi-operation-definition.html#tabdescription","title":"5.6.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram","level":"4","number":"10.6.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram","title":"5.6.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data","level":"4","number":"10.6.1.3","path":"10-tabapi-operation-definition.html#tabinput-data","title":"5.6.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour","level":"4","number":"10.6.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour","title":"5.6.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data","level":"4","number":"10.6.1.5","path":"10-tabapi-operation-definition.html#taboutput-data","title":"5.6.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-attributes","level":"3","number":"10.6.2","path":"10-tabapi-operation-definition.html#tabupdate-attributes","title":"5.6.2 Update Attributes"},"subsections":[{"section":{"id":"tabdescription-1","level":"4","number":"10.6.2.1","path":"10-tabapi-operation-definition.html#tabdescription-1","title":"5.6.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-1","level":"4","number":"10.6.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-1","title":"5.6.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-1","level":"4","number":"10.6.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-1","title":"5.6.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-1","level":"4","number":"10.6.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-1","title":"5.6.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-1","level":"4","number":"10.6.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-1","title":"5.6.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabappend-attributes","level":"3","number":"10.6.3","path":"10-tabapi-operation-definition.html#tabappend-attributes","title":"5.6.3 Append Attributes"},"subsections":[{"section":{"id":"tabdescription-2","level":"4","number":"10.6.3.1","path":"10-tabapi-operation-definition.html#tabdescription-2","title":"5.6.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-2","level":"4","number":"10.6.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-2","title":"5.6.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-2","level":"4","number":"10.6.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-2","title":"5.6.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-2","level":"4","number":"10.6.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-2","title":"5.6.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-2","level":"4","number":"10.6.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-2","title":"5.6.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabpartial-attribute-update","level":"3","number":"10.6.4","path":"10-tabapi-operation-definition.html#tabpartial-attribute-update","title":"5.6.4 Partial Attribute update"},"subsections":[{"section":{"id":"tabdescription-3","level":"4","number":"10.6.4.1","path":"10-tabapi-operation-definition.html#tabdescription-3","title":"5.6.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-3","level":"4","number":"10.6.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-3","title":"5.6.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-3","level":"4","number":"10.6.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-3","title":"5.6.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-3","level":"4","number":"10.6.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-3","title":"5.6.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-3","level":"4","number":"10.6.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-3","title":"5.6.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute","level":"3","number":"10.6.5","path":"10-tabapi-operation-definition.html#tabdelete-attribute","title":"5.6.5 Delete Attribute"},"subsections":[{"section":{"id":"tabdescription-4","level":"4","number":"10.6.5.1","path":"10-tabapi-operation-definition.html#tabdescription-4","title":"5.6.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-4","level":"4","number":"10.6.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-4","title":"5.6.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-4","level":"4","number":"10.6.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-4","title":"5.6.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-4","level":"4","number":"10.6.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-4","title":"5.6.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-4","level":"4","number":"10.6.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-4","title":"5.6.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-entity","level":"3","number":"10.6.6","path":"10-tabapi-operation-definition.html#tabdelete-entity","title":"5.6.6 Delete Entity"},"subsections":[{"section":{"id":"tabdescription-5","level":"4","number":"10.6.6.1","path":"10-tabapi-operation-definition.html#tabdescription-5","title":"5.6.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-5","level":"4","number":"10.6.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-5","title":"5.6.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-5","level":"4","number":"10.6.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-5","title":"5.6.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-5","level":"4","number":"10.6.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-5","title":"5.6.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-5","level":"4","number":"10.6.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-5","title":"5.6.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation","level":"3","number":"10.6.7","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation","title":"5.6.7 Batch Entity Creation"},"subsections":[{"section":{"id":"tabdescription-6","level":"4","number":"10.6.7.1","path":"10-tabapi-operation-definition.html#tabdescription-6","title":"5.6.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-6","level":"4","number":"10.6.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-6","title":"5.6.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-6","level":"4","number":"10.6.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-6","title":"5.6.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-6","level":"4","number":"10.6.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-6","title":"5.6.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-6","level":"4","number":"10.6.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-6","title":"5.6.7.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert","level":"3","number":"10.6.8","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert","title":"5.6.8 Batch Entity Creation or Update (Upsert)"},"subsections":[{"section":{"id":"tabdescription-7","level":"4","number":"10.6.8.1","path":"10-tabapi-operation-definition.html#tabdescription-7","title":"5.6.8.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-7","level":"4","number":"10.6.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-7","title":"5.6.8.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-7","level":"4","number":"10.6.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-7","title":"5.6.8.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-7","level":"4","number":"10.6.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-7","title":"5.6.8.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-7","level":"4","number":"10.6.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-7","title":"5.6.8.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-update","level":"3","number":"10.6.9","path":"10-tabapi-operation-definition.html#tabbatch-entity-update","title":"5.6.9 Batch Entity Update"},"subsections":[{"section":{"id":"tabdescription-8","level":"4","number":"10.6.9.1","path":"10-tabapi-operation-definition.html#tabdescription-8","title":"5.6.9.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-8","level":"4","number":"10.6.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-8","title":"5.6.9.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-8","level":"4","number":"10.6.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-8","title":"5.6.9.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-8","level":"4","number":"10.6.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-8","title":"5.6.9.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-8","level":"4","number":"10.6.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-8","title":"5.6.9.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-delete","level":"3","number":"10.6.10","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete","title":"5.6.10 Batch Entity Delete"},"subsections":[{"section":{"id":"tabdescription-9","level":"4","number":"10.6.10.1","path":"10-tabapi-operation-definition.html#tabdescription-9","title":"5.6.10.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-9","level":"4","number":"10.6.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-9","title":"5.6.10.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-9","level":"4","number":"10.6.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-9","title":"5.6.10.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-9","level":"4","number":"10.6.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-9","title":"5.6.10.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-9","level":"4","number":"10.6.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-9","title":"5.6.10.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-or-update-upsert-temporal-evolution-of-an-entity","level":"3","number":"10.6.11","path":"10-tabapi-operation-definition.html#tabcreate-or-update-upsert-temporal-evolution-of-an-entity","title":"5.6.11 Create or Update (Upsert) Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-10","level":"4","number":"10.6.11.1","path":"10-tabapi-operation-definition.html#tabdescription-10","title":"5.6.11.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-10","level":"4","number":"10.6.11.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-10","title":"5.6.11.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-10","level":"4","number":"10.6.11.3","path":"10-tabapi-operation-definition.html#tabinput-data-10","title":"5.6.11.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-10","level":"4","number":"10.6.11.4","path":"10-tabapi-operation-definition.html#tabbehaviour-10","title":"5.6.11.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-10","level":"4","number":"10.6.11.5","path":"10-tabapi-operation-definition.html#taboutput-data-10","title":"5.6.11.5 Output data"},"subsections":[]}]},{"section":{"id":"tabadd-attributes-to-temporal-evolution-of-an-entity","level":"3","number":"10.6.12","path":"10-tabapi-operation-definition.html#tabadd-attributes-to-temporal-evolution-of-an-entity","title":"5.6.12 Add Attributes to Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-11","level":"4","number":"10.6.12.1","path":"10-tabapi-operation-definition.html#tabdescription-11","title":"5.6.12.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-11","level":"4","number":"10.6.12.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-11","title":"5.6.12.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-11","level":"4","number":"10.6.12.3","path":"10-tabapi-operation-definition.html#tabinput-data-11","title":"5.6.12.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-11","level":"4","number":"10.6.12.4","path":"10-tabapi-operation-definition.html#tabbehaviour-11","title":"5.6.12.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-11","level":"4","number":"10.6.12.5","path":"10-tabapi-operation-definition.html#taboutput-data-11","title":"5.6.12.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.13","path":"10-tabapi-operation-definition.html#tabdelete-attribute-from-temporal-evolution-of-an-entity","title":"5.6.13 Delete Attribute from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-12","level":"4","number":"10.6.13.1","path":"10-tabapi-operation-definition.html#tabdescription-12","title":"5.6.13.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-12","level":"4","number":"10.6.13.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-12","title":"5.6.13.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-12","level":"4","number":"10.6.13.3","path":"10-tabapi-operation-definition.html#tabinput-data-12","title":"5.6.13.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-12","level":"4","number":"10.6.13.4","path":"10-tabapi-operation-definition.html#tabbehaviour-12","title":"5.6.13.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-12","level":"4","number":"10.6.13.5","path":"10-tabapi-operation-definition.html#taboutput-data-12","title":"5.6.13.5 Output data"},"subsections":[]}]},{"section":{"id":"tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","level":"3","number":"10.6.14","path":"10-tabapi-operation-definition.html#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","title":"5.6.14 Modify Attribute instance in Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-13","level":"4","number":"10.6.14.1","path":"10-tabapi-operation-definition.html#tabdescription-13","title":"5.6.14.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-13","level":"4","number":"10.6.14.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-13","title":"5.6.14.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-13","level":"4","number":"10.6.14.3","path":"10-tabapi-operation-definition.html#tabinput-data-13","title":"5.6.14.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-13","level":"4","number":"10.6.14.4","path":"10-tabapi-operation-definition.html#tabbehaviour-13","title":"5.6.14.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-13","level":"4","number":"10.6.14.5","path":"10-tabapi-operation-definition.html#taboutput-data-13","title":"5.6.14.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.15","path":"10-tabapi-operation-definition.html#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","title":"5.6.15 Delete Attribute instance from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-14","level":"4","number":"10.6.15.1","path":"10-tabapi-operation-definition.html#tabdescription-14","title":"5.6.15.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-14","level":"4","number":"10.6.15.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-14","title":"5.6.15.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-14","level":"4","number":"10.6.15.3","path":"10-tabapi-operation-definition.html#tabinput-data-14","title":"5.6.15.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-14","level":"4","number":"10.6.15.4","path":"10-tabapi-operation-definition.html#tabbehaviour-14","title":"5.6.15.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-14","level":"4","number":"10.6.15.5","path":"10-tabapi-operation-definition.html#taboutput-data-14","title":"5.6.15.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-temporal-evolution-of-an-entity","level":"3","number":"10.6.16","path":"10-tabapi-operation-definition.html#tabdelete-temporal-evolution-of-an-entity","title":"5.6.16 Delete Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-15","level":"4","number":"10.6.16.1","path":"10-tabapi-operation-definition.html#tabdescription-15","title":"5.6.16.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-15","level":"4","number":"10.6.16.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-15","title":"5.6.16.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-15","level":"4","number":"10.6.16.3","path":"10-tabapi-operation-definition.html#tabinput-data-15","title":"5.6.16.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-15","level":"4","number":"10.6.16.4","path":"10-tabapi-operation-definition.html#tabbehaviour-15","title":"5.6.16.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-15","level":"4","number":"10.6.16.5","path":"10-tabapi-operation-definition.html#taboutput-data-15","title":"5.6.16.5 Output data"},"subsections":[]}]},{"section":{"id":"tabmerge-entity","level":"3","number":"10.6.17","path":"10-tabapi-operation-definition.html#tabmerge-entity","title":"5.6.17 Merge Entity"},"subsections":[{"section":{"id":"tabdescription-16","level":"4","number":"10.6.17.1","path":"10-tabapi-operation-definition.html#tabdescription-16","title":"5.6.17.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-16","level":"4","number":"10.6.17.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-16","title":"5.6.17.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-16","level":"4","number":"10.6.17.3","path":"10-tabapi-operation-definition.html#tabinput-data-16","title":"5.6.17.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-16","level":"4","number":"10.6.17.4","path":"10-tabapi-operation-definition.html#tabbehaviour-16","title":"5.6.17.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-16","level":"4","number":"10.6.17.5","path":"10-tabapi-operation-definition.html#taboutput-data-16","title":"5.6.17.5 Output data"},"subsections":[]}]},{"section":{"id":"tabreplace-entity","level":"3","number":"10.6.18","path":"10-tabapi-operation-definition.html#tabreplace-entity","title":"5.6.18 Replace Entity"},"subsections":[{"section":{"id":"tabdescription-17","level":"4","number":"10.6.18.1","path":"10-tabapi-operation-definition.html#tabdescription-17","title":"5.6.18.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-17","level":"4","number":"10.6.18.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-17","title":"5.6.18.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-17","level":"4","number":"10.6.18.3","path":"10-tabapi-operation-definition.html#tabinput-data-17","title":"5.6.18.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-17","level":"4","number":"10.6.18.4","path":"10-tabapi-operation-definition.html#tabbehaviour-17","title":"5.6.18.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-17","level":"4","number":"10.6.18.5","path":"10-tabapi-operation-definition.html#taboutput-data-17","title":"5.6.18.5 Output data"},"subsections":[]}]},{"section":{"id":"tabreplace-attribute","level":"3","number":"10.6.19","path":"10-tabapi-operation-definition.html#tabreplace-attribute","title":"5.6.19 Replace Attribute"},"subsections":[{"section":{"id":"tabdescription-18","level":"4","number":"10.6.19.1","path":"10-tabapi-operation-definition.html#tabdescription-18","title":"5.6.19.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-18","level":"4","number":"10.6.19.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-18","title":"5.6.19.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-18","level":"4","number":"10.6.19.3","path":"10-tabapi-operation-definition.html#tabinput-data-18","title":"5.6.19.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-18","level":"4","number":"10.6.19.4","path":"10-tabapi-operation-definition.html#tabbehaviour-18","title":"5.6.19.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-18","level":"4","number":"10.6.19.5","path":"10-tabapi-operation-definition.html#taboutput-data-18","title":"5.6.19.5 Output data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-merge","level":"3","number":"10.6.20","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge","title":"5.6.20 Batch Entity Merge"},"subsections":[{"section":{"id":"tabdescription-19","level":"4","number":"10.6.20.1","path":"10-tabapi-operation-definition.html#tabdescription-19","title":"5.6.20.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-19","level":"4","number":"10.6.20.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-19","title":"5.6.20.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-19","level":"4","number":"10.6.20.3","path":"10-tabapi-operation-definition.html#tabinput-data-19","title":"5.6.20.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-19","level":"4","number":"10.6.20.4","path":"10-tabapi-operation-definition.html#tabbehaviour-19","title":"5.6.20.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-19","level":"4","number":"10.6.20.5","path":"10-tabapi-operation-definition.html#taboutput-data-19","title":"5.6.20.5 Output data"},"subsections":[]}]},{"section":{"id":"tabpurge-entities","level":"3","number":"10.6.21","path":"10-tabapi-operation-definition.html#tabpurge-entities","title":"5.6.21 Purge Entities"},"subsections":[{"section":{"id":"tabdescription-20","level":"4","number":"10.6.21.1","path":"10-tabapi-operation-definition.html#tabdescription-20","title":"5.6.21.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-20","level":"4","number":"10.6.21.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-20","title":"5.6.21.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-20","level":"4","number":"10.6.21.3","path":"10-tabapi-operation-definition.html#tabinput-data-20","title":"5.6.21.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-20","level":"4","number":"10.6.21.4","path":"10-tabapi-operation-definition.html#tabbehaviour-20","title":"5.6.21.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-20","level":"4","number":"10.6.21.5","path":"10-tabapi-operation-definition.html#taboutput-data-20","title":"5.6.21.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-information-consumption","level":"2","number":"10.7","path":"10-tabapi-operation-definition.html#tabcontext-information-consumption","title":"5.7 Context Information Consumption"},"subsections":[{"section":{"id":"tabretrieve-entity","level":"3","number":"10.7.1","path":"10-tabapi-operation-definition.html#tabretrieve-entity","title":"5.7.1 Retrieve Entity"},"subsections":[{"section":{"id":"tabdescription-21","level":"4","number":"10.7.1.1","path":"10-tabapi-operation-definition.html#tabdescription-21","title":"5.7.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-21","level":"4","number":"10.7.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-21","title":"5.7.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-21","level":"4","number":"10.7.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-21","title":"5.7.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-21","level":"4","number":"10.7.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-21","title":"5.7.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-21","level":"4","number":"10.7.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-21","title":"5.7.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-entities","level":"3","number":"10.7.2","path":"10-tabapi-operation-definition.html#tabquery-entities","title":"5.7.2 Query Entities"},"subsections":[{"section":{"id":"tabdescription-22","level":"4","number":"10.7.2.1","path":"10-tabapi-operation-definition.html#tabdescription-22","title":"5.7.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-22","level":"4","number":"10.7.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-22","title":"5.7.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-22","level":"4","number":"10.7.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-22","title":"5.7.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-22","level":"4","number":"10.7.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-22","title":"5.7.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-22","level":"4","number":"10.7.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-22","title":"5.7.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-temporal-evolution-of-an-entity","level":"3","number":"10.7.3","path":"10-tabapi-operation-definition.html#tabretrieve-temporal-evolution-of-an-entity","title":"5.7.3 Retrieve Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-23","level":"4","number":"10.7.3.1","path":"10-tabapi-operation-definition.html#tabdescription-23","title":"5.7.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-23","level":"4","number":"10.7.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-23","title":"5.7.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-23","level":"4","number":"10.7.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-23","title":"5.7.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-23","level":"4","number":"10.7.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-23","title":"5.7.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-23","level":"4","number":"10.7.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-23","title":"5.7.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-temporal-evolution-of-entities","level":"3","number":"10.7.4","path":"10-tabapi-operation-definition.html#tabquery-temporal-evolution-of-entities","title":"5.7.4 Query Temporal Evolution of Entities"},"subsections":[{"section":{"id":"tabdescription-24","level":"4","number":"10.7.4.1","path":"10-tabapi-operation-definition.html#tabdescription-24","title":"5.7.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-24","level":"4","number":"10.7.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-24","title":"5.7.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-24","level":"4","number":"10.7.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-24","title":"5.7.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-24","level":"4","number":"10.7.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-24","title":"5.7.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-24","level":"4","number":"10.7.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-24","title":"5.7.4.5 Output Data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-types","level":"3","number":"10.7.5","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-types","title":"5.7.5 Retrieve Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-25","level":"4","number":"10.7.5.1","path":"10-tabapi-operation-definition.html#tabdescription-25","title":"5.7.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-25","level":"4","number":"10.7.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-25","title":"5.7.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-25","level":"4","number":"10.7.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-25","title":"5.7.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-25","level":"4","number":"10.7.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-25","title":"5.7.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-25","level":"4","number":"10.7.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-25","title":"5.7.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-entity-types","level":"3","number":"10.7.6","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-entity-types","title":"5.7.6 Retrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-26","level":"4","number":"10.7.6.1","path":"10-tabapi-operation-definition.html#tabdescription-26","title":"5.7.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-26","level":"4","number":"10.7.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-26","title":"5.7.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-26","level":"4","number":"10.7.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-26","title":"5.7.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-26","level":"4","number":"10.7.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-26","title":"5.7.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-26","level":"4","number":"10.7.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-26","title":"5.7.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-type-information","level":"3","number":"10.7.7","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-type-information","title":"5.7.7 Retrieve Available Entity Type Information"},"subsections":[{"section":{"id":"tabdescription-27","level":"4","number":"10.7.7.1","path":"10-tabapi-operation-definition.html#tabdescription-27","title":"5.7.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-27","level":"4","number":"10.7.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-27","title":"5.7.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-27","level":"4","number":"10.7.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-27","title":"5.7.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-27","level":"4","number":"10.7.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-27","title":"5.7.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-27","level":"4","number":"10.7.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-27","title":"5.7.7.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attributes","level":"3","number":"10.7.8","path":"10-tabapi-operation-definition.html#tabretrieve-available-attributes","title":"5.7.8 Retrieve Available Attributes"},"subsections":[{"section":{"id":"tabdescription-28","level":"4","number":"10.7.8.1","path":"10-tabapi-operation-definition.html#tabdescription-28","title":"5.7.8.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-28","level":"4","number":"10.7.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-28","title":"5.7.8.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-28","level":"4","number":"10.7.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-28","title":"5.7.8.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-28","level":"4","number":"10.7.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-28","title":"5.7.8.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-28","level":"4","number":"10.7.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-28","title":"5.7.8.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-attributes","level":"3","number":"10.7.9","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-attributes","title":"5.7.9 Retrieve Details of Available Attributes"},"subsections":[{"section":{"id":"tabdescription-29","level":"4","number":"10.7.9.1","path":"10-tabapi-operation-definition.html#tabdescription-29","title":"5.7.9.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-29","level":"4","number":"10.7.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-29","title":"5.7.9.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-29","level":"4","number":"10.7.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-29","title":"5.7.9.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-29","level":"4","number":"10.7.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-29","title":"5.7.9.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-29","level":"4","number":"10.7.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-29","title":"5.7.9.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attribute-information","level":"3","number":"10.7.10","path":"10-tabapi-operation-definition.html#tabretrieve-available-attribute-information","title":"5.7.10 Retrieve Available Attribute Information"},"subsections":[{"section":{"id":"tabdescription-30","level":"4","number":"10.7.10.1","path":"10-tabapi-operation-definition.html#tabdescription-30","title":"5.7.10.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-30","level":"4","number":"10.7.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-30","title":"5.7.10.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-30","level":"4","number":"10.7.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-30","title":"5.7.10.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-30","level":"4","number":"10.7.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-30","title":"5.7.10.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-30","level":"4","number":"10.7.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-30","title":"5.7.10.5 Output data"},"subsections":[]}]},{"section":{"id":"tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","level":"3","number":"10.7.11","path":"10-tabapi-operation-definition.html#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","title":"5.7.11 Architecture-related aspects of retrieval of Entity Types and Attributes"},"subsections":[]}]},{"section":{"id":"tabcontext-information-subscription","level":"2","number":"10.8","path":"10-tabapi-operation-definition.html#tabcontext-information-subscription","title":"5.8 Context Information Subscription"},"subsections":[{"section":{"id":"tabcreate-subscription","level":"3","number":"10.8.1","path":"10-tabapi-operation-definition.html#tabcreate-subscription","title":"5.8.1 Create Subscription"},"subsections":[{"section":{"id":"tabdescription-31","level":"4","number":"10.8.1.1","path":"10-tabapi-operation-definition.html#tabdescription-31","title":"5.8.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-31","level":"4","number":"10.8.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-31","title":"5.8.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-31","level":"4","number":"10.8.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-31","title":"5.8.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-31","level":"4","number":"10.8.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-31","title":"5.8.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-31","level":"4","number":"10.8.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-31","title":"5.8.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-subscription","level":"3","number":"10.8.2","path":"10-tabapi-operation-definition.html#tabupdate-subscription","title":"5.8.2 Update Subscription"},"subsections":[{"section":{"id":"tabdescription-32","level":"4","number":"10.8.2.1","path":"10-tabapi-operation-definition.html#tabdescription-32","title":"5.8.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-32","level":"4","number":"10.8.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-32","title":"5.8.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-32","level":"4","number":"10.8.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-32","title":"5.8.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-32","level":"4","number":"10.8.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-32","title":"5.8.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-32","level":"4","number":"10.8.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-32","title":"5.8.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-subscription","level":"3","number":"10.8.3","path":"10-tabapi-operation-definition.html#tabretrieve-subscription","title":"5.8.3 Retrieve Subscription"},"subsections":[{"section":{"id":"tabdescription-33","level":"4","number":"10.8.3.1","path":"10-tabapi-operation-definition.html#tabdescription-33","title":"5.8.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-33","level":"4","number":"10.8.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-33","title":"5.8.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-33","level":"4","number":"10.8.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-33","title":"5.8.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-33","level":"4","number":"10.8.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-33","title":"5.8.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-33","level":"4","number":"10.8.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-33","title":"5.8.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-subscriptions","level":"3","number":"10.8.4","path":"10-tabapi-operation-definition.html#tabquery-subscriptions","title":"5.8.4 Query Subscriptions"},"subsections":[{"section":{"id":"tabdescription-34","level":"4","number":"10.8.4.1","path":"10-tabapi-operation-definition.html#tabdescription-34","title":"5.8.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-34","level":"4","number":"10.8.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-34","title":"5.8.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-34","level":"4","number":"10.8.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-34","title":"5.8.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-34","level":"4","number":"10.8.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-34","title":"5.8.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-34","level":"4","number":"10.8.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-34","title":"5.8.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-subscription","level":"3","number":"10.8.5","path":"10-tabapi-operation-definition.html#tabdelete-subscription","title":"5.8.5 Delete Subscription"},"subsections":[{"section":{"id":"tabdescription-35","level":"4","number":"10.8.5.1","path":"10-tabapi-operation-definition.html#tabdescription-35","title":"5.8.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-35","level":"4","number":"10.8.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-35","title":"5.8.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-35","level":"4","number":"10.8.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-35","title":"5.8.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-35","level":"4","number":"10.8.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-35","title":"5.8.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-35","level":"4","number":"10.8.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-35","title":"5.8.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour","level":"3","number":"10.8.6","path":"10-tabapi-operation-definition.html#tabnotification-behaviour","title":"5.8.6 Notification behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-source-registration","level":"2","number":"10.9","path":"10-tabapi-operation-definition.html#tabcontext-source-registration","title":"5.9 Context Source Registration"},"subsections":[{"section":{"id":"tabintroduction-18","level":"3","number":"10.9.1","path":"10-tabapi-operation-definition.html#tabintroduction-18","title":"5.9.1 Introduction"},"subsections":[]},{"section":{"id":"tabregister-context-source","level":"3","number":"10.9.2","path":"10-tabapi-operation-definition.html#tabregister-context-source","title":"5.9.2 Register Context Source"},"subsections":[{"section":{"id":"tabdescription-36","level":"4","number":"10.9.2.1","path":"10-tabapi-operation-definition.html#tabdescription-36","title":"5.9.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-36","level":"4","number":"10.9.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-36","title":"5.9.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-36","level":"4","number":"10.9.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-36","title":"5.9.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-36","level":"4","number":"10.9.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-36","title":"5.9.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-36","level":"4","number":"10.9.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-36","title":"5.9.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration","level":"3","number":"10.9.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration","title":"5.9.3 Update Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-37","level":"4","number":"10.9.3.1","path":"10-tabapi-operation-definition.html#tabdescription-37","title":"5.9.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-37","level":"4","number":"10.9.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-37","title":"5.9.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-37","level":"4","number":"10.9.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-37","title":"5.9.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-37","level":"4","number":"10.9.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-37","title":"5.9.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-37","level":"4","number":"10.9.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-37","title":"5.9.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration","level":"3","number":"10.9.4","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration","title":"5.9.4 Delete Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-38","level":"4","number":"10.9.4.1","path":"10-tabapi-operation-definition.html#tabdescription-38","title":"5.9.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-38","level":"4","number":"10.9.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-38","title":"5.9.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-38","level":"4","number":"10.9.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-38","title":"5.9.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-38","level":"4","number":"10.9.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-38","title":"5.9.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-38","level":"4","number":"10.9.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-38","title":"5.9.4.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-discovery","level":"2","number":"10.10","path":"10-tabapi-operation-definition.html#tabcontext-source-discovery","title":"5.10 Context Source Discovery"},"subsections":[{"section":{"id":"tabretrieve-context-source-registration","level":"3","number":"10.10.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration","title":"5.10.1 Retrieve Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-39","level":"4","number":"10.10.1.1","path":"10-tabapi-operation-definition.html#tabdescription-39","title":"5.10.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-39","level":"4","number":"10.10.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-39","title":"5.10.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-39","level":"4","number":"10.10.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-39","title":"5.10.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-39","level":"4","number":"10.10.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-39","title":"5.10.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-39","level":"4","number":"10.10.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-39","title":"5.10.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registrations","level":"3","number":"10.10.2","path":"10-tabapi-operation-definition.html#tabquery-context-source-registrations","title":"5.10.2 Query Context Source Registrations"},"subsections":[{"section":{"id":"tabdescription-40","level":"4","number":"10.10.2.1","path":"10-tabapi-operation-definition.html#tabdescription-40","title":"5.10.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-40","level":"4","number":"10.10.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-40","title":"5.10.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-40","level":"4","number":"10.10.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-40","title":"5.10.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-40","level":"4","number":"10.10.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-40","title":"5.10.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-40","level":"4","number":"10.10.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-40","title":"5.10.2.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-registration-subscription","level":"2","number":"10.11","path":"10-tabapi-operation-definition.html#tabcontext-source-registration-subscription","title":"5.11 Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabintroduction-19","level":"3","number":"10.11.1","path":"10-tabapi-operation-definition.html#tabintroduction-19","title":"5.11.1 Introduction"},"subsections":[]},{"section":{"id":"tabcreate-context-source-registration-subscription","level":"3","number":"10.11.2","path":"10-tabapi-operation-definition.html#tabcreate-context-source-registration-subscription","title":"5.11.2 Create Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-41","level":"4","number":"10.11.2.1","path":"10-tabapi-operation-definition.html#tabdescription-41","title":"5.11.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-41","level":"4","number":"10.11.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-41","title":"5.11.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-41","level":"4","number":"10.11.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-41","title":"5.11.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-41","level":"4","number":"10.11.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-41","title":"5.11.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-41","level":"4","number":"10.11.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-41","title":"5.11.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration-subscription","level":"3","number":"10.11.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration-subscription","title":"5.11.3 Update Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-42","level":"4","number":"10.11.3.1","path":"10-tabapi-operation-definition.html#tabdescription-42","title":"5.11.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-42","level":"4","number":"10.11.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-42","title":"5.11.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-42","level":"4","number":"10.11.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-42","title":"5.11.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-42","level":"4","number":"10.11.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-42","title":"5.11.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-42","level":"4","number":"10.11.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-42","title":"5.11.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-context-source-registration-subscription","level":"3","number":"10.11.4","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration-subscription","title":"5.11.4 Retrieve Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-43","level":"4","number":"10.11.4.1","path":"10-tabapi-operation-definition.html#tabdescription-43","title":"5.11.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-43","level":"4","number":"10.11.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-43","title":"5.11.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-43","level":"4","number":"10.11.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-43","title":"5.11.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-43","level":"4","number":"10.11.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-43","title":"5.11.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-43","level":"4","number":"10.11.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-43","title":"5.11.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registration-subscriptions","level":"3","number":"10.11.5","path":"10-tabapi-operation-definition.html#tabquery-context-source-registration-subscriptions","title":"5.11.5 Query Context Source Registration Subscriptions"},"subsections":[{"section":{"id":"tabdescription-44","level":"4","number":"10.11.5.1","path":"10-tabapi-operation-definition.html#tabdescription-44","title":"5.11.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-44","level":"4","number":"10.11.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-44","title":"5.11.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-44","level":"4","number":"10.11.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-44","title":"5.11.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-44","level":"4","number":"10.11.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-44","title":"5.11.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-44","level":"4","number":"10.11.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-44","title":"5.11.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration-subscription","level":"3","number":"10.11.6","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration-subscription","title":"5.11.6 Delete Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-45","level":"4","number":"10.11.6.1","path":"10-tabapi-operation-definition.html#tabdescription-45","title":"5.11.6.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-45","level":"4","number":"10.11.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-45","title":"5.11.6.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-45","level":"4","number":"10.11.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-45","title":"5.11.6.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-45","level":"4","number":"10.11.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-45","title":"5.11.6.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-45","level":"4","number":"10.11.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-45","title":"5.11.6.5 Output data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour-1","level":"3","number":"10.11.7","path":"10-tabapi-operation-definition.html#tabnotification-behaviour-1","title":"5.11.7 Notification behaviour"},"subsections":[]}]},{"section":{"id":"tabmatching-context-source-registrations","level":"2","number":"10.12","path":"10-tabapi-operation-definition.html#tabmatching-context-source-registrations","title":"5.12 Matching Context Source Registrations"},"subsections":[]},{"section":{"id":"tabstoring-managing-and-serving-contexts","level":"2","number":"10.13","path":"10-tabapi-operation-definition.html#tabstoring-managing-and-serving-contexts","title":"5.13 Storing, Managing and Serving @contexts"},"subsections":[{"section":{"id":"tabintroduction-20","level":"3","number":"10.13.1","path":"10-tabapi-operation-definition.html#tabintroduction-20","title":"5.13.1 Introduction"},"subsections":[]},{"section":{"id":"tabadd-context","level":"3","number":"10.13.2","path":"10-tabapi-operation-definition.html#tabadd-context","title":"5.13.2 Add @context"},"subsections":[{"section":{"id":"tabdescription-46","level":"4","number":"10.13.2.1","path":"10-tabapi-operation-definition.html#tabdescription-46","title":"5.13.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-46","level":"4","number":"10.13.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-46","title":"5.13.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-46","level":"4","number":"10.13.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-46","title":"5.13.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-46","level":"4","number":"10.13.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-46","title":"5.13.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-46","level":"4","number":"10.13.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-46","title":"5.13.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tablist-contexts","level":"3","number":"10.13.3","path":"10-tabapi-operation-definition.html#tablist-contexts","title":"5.13.3 List @contexts"},"subsections":[{"section":{"id":"tabdescription-47","level":"4","number":"10.13.3.1","path":"10-tabapi-operation-definition.html#tabdescription-47","title":"5.13.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-47","level":"4","number":"10.13.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-47","title":"5.13.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-47","level":"4","number":"10.13.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-47","title":"5.13.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-47","level":"4","number":"10.13.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-47","title":"5.13.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-47","level":"4","number":"10.13.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-47","title":"5.13.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabserve-context","level":"3","number":"10.13.4","path":"10-tabapi-operation-definition.html#tabserve-context","title":"5.13.4 Serve @context"},"subsections":[{"section":{"id":"tabdescription-48","level":"4","number":"10.13.4.1","path":"10-tabapi-operation-definition.html#tabdescription-48","title":"5.13.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-48","level":"4","number":"10.13.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-48","title":"5.13.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-48","level":"4","number":"10.13.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-48","title":"5.13.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-48","level":"4","number":"10.13.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-48","title":"5.13.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-48","level":"4","number":"10.13.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-48","title":"5.13.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-and-reload-context","level":"3","number":"10.13.5","path":"10-tabapi-operation-definition.html#tabdelete-and-reload-context","title":"5.13.5 Delete and Reload @context"},"subsections":[{"section":{"id":"tabdescription-49","level":"4","number":"10.13.5.1","path":"10-tabapi-operation-definition.html#tabdescription-49","title":"5.13.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-49","level":"4","number":"10.13.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-49","title":"5.13.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-49","level":"4","number":"10.13.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-49","title":"5.13.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-49","level":"4","number":"10.13.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-49","title":"5.13.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-49","level":"4","number":"10.13.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-49","title":"5.13.5.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-entity-mapping","level":"2","number":"10.14","path":"10-tabapi-operation-definition.html#tabcontext-source-entity-mapping","title":"5.14 Context Source Entity Mapping"},"subsections":[{"section":{"id":"tabretrieve-entitymap","level":"3","number":"10.14.1","path":"10-tabapi-operation-definition.html#tabretrieve-entitymap","title":"5.14.1 Retrieve EntityMap"},"subsections":[{"section":{"id":"tabdescription-50","level":"4","number":"10.14.1.1","path":"10-tabapi-operation-definition.html#tabdescription-50","title":"5.14.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-50","level":"4","number":"10.14.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-50","title":"5.14.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-50","level":"4","number":"10.14.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-50","title":"5.14.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-50","level":"4","number":"10.14.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-50","title":"5.14.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-50","level":"4","number":"10.14.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-50","title":"5.14.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-entitymap","level":"3","number":"10.14.2","path":"10-tabapi-operation-definition.html#tabupdate-entitymap","title":"5.14.2 Update EntityMap"},"subsections":[{"section":{"id":"tabdescription-51","level":"4","number":"10.14.2.1","path":"10-tabapi-operation-definition.html#tabdescription-51","title":"5.14.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-51","level":"4","number":"10.14.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-51","title":"5.14.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-51","level":"4","number":"10.14.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-51","title":"5.14.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-51","level":"4","number":"10.14.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-51","title":"5.14.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-51","level":"4","number":"10.14.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-51","title":"5.14.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabdelete-entitymap","level":"3","number":"10.14.3","path":"10-tabapi-operation-definition.html#tabdelete-entitymap","title":"5.14.3 Delete EntityMap"},"subsections":[{"section":{"id":"tabdescription-52","level":"4","number":"10.14.3.1","path":"10-tabapi-operation-definition.html#tabdescription-52","title":"5.14.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-52","level":"4","number":"10.14.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-52","title":"5.14.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-52","level":"4","number":"10.14.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-52","title":"5.14.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-52","level":"4","number":"10.14.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-52","title":"5.14.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-52","level":"4","number":"10.14.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-52","title":"5.14.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-entitymap-for-query-entities","level":"3","number":"10.14.4","path":"10-tabapi-operation-definition.html#tabcreate-entitymap-for-query-entities","title":"5.14.4 Create EntityMap for Query Entities"},"subsections":[{"section":{"id":"tabdescription-53","level":"4","number":"10.14.4.1","path":"10-tabapi-operation-definition.html#tabdescription-53","title":"5.14.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-53","level":"4","number":"10.14.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-53","title":"5.14.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-53","level":"4","number":"10.14.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-53","title":"5.14.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-53","level":"4","number":"10.14.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-53","title":"5.14.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-53","level":"4","number":"10.14.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-53","title":"5.14.4.5 Output data"},"subsections":[]}]},{"section":{"id":"tabcreate-entitymap-for-query-temporal-evolution-of-entities","level":"3","number":"10.14.5","path":"10-tabapi-operation-definition.html#tabcreate-entitymap-for-query-temporal-evolution-of-entities","title":"5.14.5 Create EntityMap for Query Temporal Evolution of Entities"},"subsections":[{"section":{"id":"tabdescription-54","level":"4","number":"10.14.5.1","path":"10-tabapi-operation-definition.html#tabdescription-54","title":"5.14.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-54","level":"4","number":"10.14.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-54","title":"5.14.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-54","level":"4","number":"10.14.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-54","title":"5.14.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-54","level":"4","number":"10.14.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-54","title":"5.14.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-54","level":"4","number":"10.14.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-54","title":"5.7.4.5 Output Data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-identity-information","level":"2","number":"10.15","path":"10-tabapi-operation-definition.html#tabcontext-source-identity-information","title":"5.15 Context Source Identity Information"},"subsections":[{"section":{"id":"tabretrieve-context-source-identity-information","level":"3","number":"10.15.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-identity-information","title":"5.15.1 Retrieve Context Source Identity Information"},"subsections":[{"section":{"id":"tabdescription-55","level":"4","number":"10.15.1.1","path":"10-tabapi-operation-definition.html#tabdescription-55","title":"5.15.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-55","level":"4","number":"10.15.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-55","title":"5.15.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-55","level":"4","number":"10.15.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-55","title":"5.15.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-55","level":"4","number":"10.15.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-55","title":"5.15.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-55","level":"4","number":"10.15.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-55","title":"5.15.1.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabsnapshot-functionality","level":"2","number":"10.16","path":"10-tabapi-operation-definition.html#tabsnapshot-functionality","title":"5.16 Snapshot Functionality"},"subsections":[{"section":{"id":"tabcreate-snapshot","level":"3","number":"10.16.1","path":"10-tabapi-operation-definition.html#tabcreate-snapshot","title":"5.16.1 Create Snapshot"},"subsections":[{"section":{"id":"tabdescription-56","level":"4","number":"10.16.1.1","path":"10-tabapi-operation-definition.html#tabdescription-56","title":"5.16.1.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-56","level":"4","number":"10.16.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-56","title":"5.16.1.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-56","level":"4","number":"10.16.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-56","title":"5.16.1.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-56","level":"4","number":"10.16.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-56","title":"5.16.1.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-56","level":"4","number":"10.16.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-56","title":"5.16.1.5 Output data"},"subsections":[]}]},{"section":{"id":"tabclone-snapshot","level":"3","number":"10.16.2","path":"10-tabapi-operation-definition.html#tabclone-snapshot","title":"5.16.2 Clone Snapshot"},"subsections":[{"section":{"id":"tabdescription-57","level":"4","number":"10.16.2.1","path":"10-tabapi-operation-definition.html#tabdescription-57","title":"5.16.2.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-57","level":"4","number":"10.16.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-57","title":"5.16.2.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-57","level":"4","number":"10.16.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-57","title":"5.16.2.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-57","level":"4","number":"10.16.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-57","title":"5.16.2.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-57","level":"4","number":"10.16.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-57","title":"5.16.2.5 Output data"},"subsections":[]}]},{"section":{"id":"tabretrieve-snapshot-status","level":"3","number":"10.16.3","path":"10-tabapi-operation-definition.html#tabretrieve-snapshot-status","title":"5.16.3 Retrieve Snapshot Status"},"subsections":[{"section":{"id":"tabdescription-58","level":"4","number":"10.16.3.1","path":"10-tabapi-operation-definition.html#tabdescription-58","title":"5.16.3.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-58","level":"4","number":"10.16.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-58","title":"5.16.3.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-58","level":"4","number":"10.16.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-58","title":"5.16.3.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-58","level":"4","number":"10.16.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-58","title":"5.16.3.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-58","level":"4","number":"10.16.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-58","title":"5.16.3.5 Output data"},"subsections":[]}]},{"section":{"id":"tabupdate-snapshot-status","level":"3","number":"10.16.4","path":"10-tabapi-operation-definition.html#tabupdate-snapshot-status","title":"5.16.4 Update Snapshot Status"},"subsections":[{"section":{"id":"tabdescription-59","level":"4","number":"10.16.4.1","path":"10-tabapi-operation-definition.html#tabdescription-59","title":"5.16.4.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-59","level":"4","number":"10.16.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-59","title":"5.16.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-59","level":"4","number":"10.16.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-59","title":"5.16.4.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-59","level":"4","number":"10.16.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-59","title":"5.16.4.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-59","level":"4","number":"10.16.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-59","title":"5.16.4.5 Output data"},"subsections":[]}]},{"section":{"id":"a-json-ld-object-representing-the-snapshot-status-as-mandated-by-clause-5.2.41.5.16.5tabdelete-snapshot","level":"3","number":"10.16.5","path":"10-tabapi-operation-definition.html#a-json-ld-object-representing-the-snapshot-status-as-mandated-by-clause-5.2.41.5.16.5tabdelete-snapshot","title":"A JSON-LD object representing the Snapshot status as mandated by clause 5.2.41.5.16.5 Delete Snapshot"},"subsections":[{"section":{"id":"tabdescription-60","level":"4","number":"10.16.5.1","path":"10-tabapi-operation-definition.html#tabdescription-60","title":"5.16.5.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-60","level":"4","number":"10.16.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-60","title":"5.16.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-60","level":"4","number":"10.16.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-60","title":"5.16.5.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-60","level":"4","number":"10.16.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-60","title":"5.16.5.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-60","level":"4","number":"10.16.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-60","title":"5.16.5.5 Output data"},"subsections":[]}]},{"section":{"id":"tabsnapshot-status-notification-behaviour","level":"3","number":"10.16.6","path":"10-tabapi-operation-definition.html#tabsnapshot-status-notification-behaviour","title":"5.16.6 Snapshot status notification behaviour"},"subsections":[]},{"section":{"id":"tabpurge-snapshots","level":"3","number":"10.16.7","path":"10-tabapi-operation-definition.html#tabpurge-snapshots","title":"5.16.7 Purge Snapshots"},"subsections":[{"section":{"id":"tabdescription-61","level":"4","number":"10.16.7.1","path":"10-tabapi-operation-definition.html#tabdescription-61","title":"5.16.7.1 Description"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-61","level":"4","number":"10.16.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-61","title":"5.16.7.2 Use case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-61","level":"4","number":"10.16.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-61","title":"5.16.7.3 Input data"},"subsections":[]},{"section":{"id":"tabbehaviour-61","level":"4","number":"10.16.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-61","title":"5.16.7.4 Behaviour"},"subsections":[]},{"section":{"id":"taboutput-data-61","level":"4","number":"10.16.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-61","title":"5.16.7.5 Output data"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-http-binding","level":"1","number":"11","path":"11-tabapi-http-binding.html#tabapi-http-binding","title":"6 API HTTP Binding"},"subsections":[{"section":{"id":"tabintroduction-21","level":"2","number":"11.1","path":"11-tabapi-http-binding.html#tabintroduction-21","title":"6.1 Introduction"},"subsections":[]},{"section":{"id":"tabglobal-definitions-and-resource-structure","level":"2","number":"11.2","path":"11-tabapi-http-binding.html#tabglobal-definitions-and-resource-structure","title":"6.2 Global Definitions and Resource Structure"},"subsections":[]},{"section":{"id":"tabcommon-behaviours-1","level":"2","number":"11.3","path":"11-tabapi-http-binding.html#tabcommon-behaviours-1","title":"6.3 Common Behaviours"},"subsections":[{"section":{"id":"tabintroduction-22","level":"3","number":"11.3.1","path":"11-tabapi-http-binding.html#tabintroduction-22","title":"6.3.1 Introduction"},"subsections":[]},{"section":{"id":"taberror-types-1","level":"3","number":"11.3.2","path":"11-tabapi-http-binding.html#taberror-types-1","title":"6.3.2 Error Types"},"subsections":[]},{"section":{"id":"tabreporting-errors","level":"3","number":"11.3.3","path":"11-tabapi-http-binding.html#tabreporting-errors","title":"6.3.3 Reporting errors"},"subsections":[]},{"section":{"id":"tabhttp-request-preconditions","level":"3","number":"11.3.4","path":"11-tabapi-http-binding.html#tabhttp-request-preconditions","title":"6.3.4 HTTP request preconditions"},"subsections":[]},{"section":{"id":"tabjson-ld-context-resolution","level":"3","number":"11.3.5","path":"11-tabapi-http-binding.html#tabjson-ld-context-resolution","title":"6.3.5 JSON-LD @context resolution"},"subsections":[]},{"section":{"id":"tabhttp-response-common-requirements","level":"3","number":"11.3.6","path":"11-tabapi-http-binding.html#tabhttp-response-common-requirements","title":"6.3.6 HTTP response common requirements"},"subsections":[]},{"section":{"id":"tabrepresentation-of-entities","level":"3","number":"11.3.7","path":"11-tabapi-http-binding.html#tabrepresentation-of-entities","title":"6.3.7 Representation of Entities"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-2","level":"3","number":"11.3.8","path":"11-tabapi-http-binding.html#tabnotification-behaviour-2","title":"6.3.8 Notification behaviour"},"subsections":[]},{"section":{"id":"tabcsource-notification-behaviour","level":"3","number":"11.3.9","path":"11-tabapi-http-binding.html#tabcsource-notification-behaviour","title":"6.3.9 Csource Notification behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour-1","level":"3","number":"11.3.10","path":"11-tabapi-http-binding.html#tabpagination-behaviour-1","title":"6.3.10 Pagination behaviour"},"subsections":[]},{"section":{"id":"tabincluding-system-attributes","level":"3","number":"11.3.11","path":"11-tabapi-http-binding.html#tabincluding-system-attributes","title":"6.3.11 Including system Attributes"},"subsections":[]},{"section":{"id":"tabsimplified-or-aggregated-temporal-representation-of-entities","level":"3","number":"11.3.12","path":"11-tabapi-http-binding.html#tabsimplified-or-aggregated-temporal-representation-of-entities","title":"6.3.12 Simplified or aggregated temporal representation of Entities"},"subsections":[]},{"section":{"id":"tabcounting-number-of-results","level":"3","number":"11.3.13","path":"11-tabapi-http-binding.html#tabcounting-number-of-results","title":"6.3.13 Counting number of results"},"subsections":[]},{"section":{"id":"tabtenant-specification","level":"3","number":"11.3.14","path":"11-tabapi-http-binding.html#tabtenant-specification","title":"6.3.14 Tenant specification"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-spatially-bound-entities","level":"3","number":"11.3.15","path":"11-tabapi-http-binding.html#tabgeojson-representation-of-spatially-bound-entities","title":"6.3.15 GeoJSON representation of spatially bound entities"},"subsections":[]},{"section":{"id":"tabexpiration-time-for-cached-contexts","level":"3","number":"11.3.16","path":"11-tabapi-http-binding.html#tabexpiration-time-for-cached-contexts","title":"6.3.16 Expiration time for cached @contexts"},"subsections":[]},{"section":{"id":"tabdistributed-operations-caching-and-timeout-behaviour","level":"3","number":"11.3.17","path":"11-tabapi-http-binding.html#tabdistributed-operations-caching-and-timeout-behaviour","title":"6.3.17 Distributed Operations Caching and Timeout Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-distributed-operations","level":"3","number":"11.3.18","path":"11-tabapi-http-binding.html#tablimiting-distributed-operations","title":"6.3.18 Limiting Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source-1","level":"3","number":"11.3.19","path":"11-tabapi-http-binding.html#tabextra-information-to-provide-when-contacting-context-source-1","title":"6.3.19 Extra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabinvalid-parameters","level":"3","number":"11.3.20","path":"11-tabapi-http-binding.html#tabinvalid-parameters","title":"6.3.20 Invalid parameters"},"subsections":[]},{"section":{"id":"taboptional-profile-information-regarding-versioning-and-datatype-conformance","level":"3","number":"11.3.21","path":"11-tabapi-http-binding.html#taboptional-profile-information-regarding-versioning-and-datatype-conformance","title":"6.3.21 Optional profile information regarding versioning and datatype conformance"},"subsections":[]},{"section":{"id":"tabsnapshot-specification","level":"3","number":"11.3.22","path":"11-tabapi-http-binding.html#tabsnapshot-specification","title":"6.3.22 Snapshot specification"},"subsections":[]}]},{"section":{"id":"tabresource-entities","level":"2","number":"11.4","path":"11-tabapi-http-binding.html#tabresource-entities","title":"6.4 Resource: entities/"},"subsections":[{"section":{"id":"tabdescription-62","level":"3","number":"11.4.1","path":"11-tabapi-http-binding.html#tabdescription-62","title":"6.4.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition","level":"3","number":"11.4.2","path":"11-tabapi-http-binding.html#tabresource-definition","title":"6.4.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods","level":"3","number":"11.4.3","path":"11-tabapi-http-binding.html#tabresource-methods","title":"6.4.3 Resource methods"},"subsections":[{"section":{"id":"tabpost","level":"4","number":"11.4.3.1","path":"11-tabapi-http-binding.html#tabpost","title":"6.4.3.1 POST"},"subsections":[]},{"section":{"id":"tabget","level":"4","number":"11.4.3.2","path":"11-tabapi-http-binding.html#tabget","title":"6.4.3.2 GET"},"subsections":[]},{"section":{"id":"tabdelete","level":"4","number":"11.4.3.3","path":"11-tabapi-http-binding.html#tabdelete","title":"6.4.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityid","level":"2","number":"11.5","path":"11-tabapi-http-binding.html#tabresource-entitiesentityid","title":"6.5 Resource: entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-63","level":"3","number":"11.5.1","path":"11-tabapi-http-binding.html#tabdescription-63","title":"6.5.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-1","level":"3","number":"11.5.2","path":"11-tabapi-http-binding.html#tabresource-definition-1","title":"6.5.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-1","level":"3","number":"11.5.3","path":"11-tabapi-http-binding.html#tabresource-methods-1","title":"6.5.3 Resource methods"},"subsections":[{"section":{"id":"tabget-1","level":"4","number":"11.5.3.1","path":"11-tabapi-http-binding.html#tabget-1","title":"6.5.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-1","level":"4","number":"11.5.3.2","path":"11-tabapi-http-binding.html#tabdelete-1","title":"6.5.3.2 DELETE"},"subsections":[]},{"section":{"id":"tabput","level":"4","number":"11.5.3.3","path":"11-tabapi-http-binding.html#tabput","title":"6.5.3.3 PUT"},"subsections":[]},{"section":{"id":"tabpatch","level":"4","number":"11.5.3.4","path":"11-tabapi-http-binding.html#tabpatch","title":"6.5.3.4 PATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrs","level":"2","number":"11.6","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrs","title":"6.6 Resource: entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-64","level":"3","number":"11.6.1","path":"11-tabapi-http-binding.html#tabdescription-64","title":"6.6.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-2","level":"3","number":"11.6.2","path":"11-tabapi-http-binding.html#tabresource-definition-2","title":"6.6.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-2","level":"3","number":"11.6.3","path":"11-tabapi-http-binding.html#tabresource-methods-2","title":"6.6.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-1","level":"4","number":"11.6.3.1","path":"11-tabapi-http-binding.html#tabpost-1","title":"6.6.3.1 POST"},"subsections":[]},{"section":{"id":"tabpatch-1","level":"4","number":"11.6.3.2","path":"11-tabapi-http-binding.html#tabpatch-1","title":"6.6.3.2 PATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrsattrid","level":"2","number":"11.7","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrsattrid","title":"6.7 Resource: entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-65","level":"3","number":"11.7.1","path":"11-tabapi-http-binding.html#tabdescription-65","title":"6.7.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-3","level":"3","number":"11.7.2","path":"11-tabapi-http-binding.html#tabresource-definition-3","title":"6.7.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-3","level":"3","number":"11.7.3","path":"11-tabapi-http-binding.html#tabresource-methods-3","title":"6.7.3 Resource methods"},"subsections":[{"section":{"id":"tabpatch-2","level":"4","number":"11.7.3.1","path":"11-tabapi-http-binding.html#tabpatch-2","title":"6.7.3.1 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-2","level":"4","number":"11.7.3.2","path":"11-tabapi-http-binding.html#tabdelete-2","title":"6.7.3.2 DELETE"},"subsections":[]},{"section":{"id":"tabput-1","level":"4","number":"11.7.3.3","path":"11-tabapi-http-binding.html#tabput-1","title":"6.7.3.3 PUT"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrations","level":"2","number":"11.8","path":"11-tabapi-http-binding.html#tabresource-csourceregistrations","title":"6.8 Resource: csourceRegistrations/"},"subsections":[{"section":{"id":"tabdescription-66","level":"3","number":"11.8.1","path":"11-tabapi-http-binding.html#tabdescription-66","title":"6.8.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-4","level":"3","number":"11.8.2","path":"11-tabapi-http-binding.html#tabresource-definition-4","title":"6.8.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-4","level":"3","number":"11.8.3","path":"11-tabapi-http-binding.html#tabresource-methods-4","title":"6.8.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-2","level":"4","number":"11.8.3.1","path":"11-tabapi-http-binding.html#tabpost-2","title":"6.8.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-2","level":"4","number":"11.8.3.2","path":"11-tabapi-http-binding.html#tabget-2","title":"6.8.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrationsregistrationid","level":"2","number":"11.9","path":"11-tabapi-http-binding.html#tabresource-csourceregistrationsregistrationid","title":"6.9 Resource: csourceRegistrations/{registrationId}"},"subsections":[{"section":{"id":"tabdescription-67","level":"3","number":"11.9.1","path":"11-tabapi-http-binding.html#tabdescription-67","title":"6.9.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-5","level":"3","number":"11.9.2","path":"11-tabapi-http-binding.html#tabresource-definition-5","title":"6.9.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-5","level":"3","number":"11.9.3","path":"11-tabapi-http-binding.html#tabresource-methods-5","title":"6.9.3 Resource methods"},"subsections":[{"section":{"id":"tabget-3","level":"4","number":"11.9.3.1","path":"11-tabapi-http-binding.html#tabget-3","title":"6.9.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-3","level":"4","number":"11.9.3.2","path":"11-tabapi-http-binding.html#tabpatch-3","title":"6.9.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-3","level":"4","number":"11.9.3.3","path":"11-tabapi-http-binding.html#tabdelete-3","title":"6.9.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptions","level":"2","number":"11.10","path":"11-tabapi-http-binding.html#tabresource-subscriptions","title":"6.10 Resource: subscriptions/"},"subsections":[{"section":{"id":"tabdescription-68","level":"3","number":"11.10.1","path":"11-tabapi-http-binding.html#tabdescription-68","title":"6.10.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-6","level":"3","number":"11.10.2","path":"11-tabapi-http-binding.html#tabresource-definition-6","title":"6.10.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-6","level":"3","number":"11.10.3","path":"11-tabapi-http-binding.html#tabresource-methods-6","title":"6.10.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-3","level":"4","number":"11.10.3.1","path":"11-tabapi-http-binding.html#tabpost-3","title":"6.10.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-4","level":"4","number":"11.10.3.2","path":"11-tabapi-http-binding.html#tabget-4","title":"6.10.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptionssubscriptionid","level":"2","number":"11.11","path":"11-tabapi-http-binding.html#tabresource-subscriptionssubscriptionid","title":"6.11 Resource: subscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-69","level":"3","number":"11.11.1","path":"11-tabapi-http-binding.html#tabdescription-69","title":"6.11.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-7","level":"3","number":"11.11.2","path":"11-tabapi-http-binding.html#tabresource-definition-7","title":"6.11.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-7","level":"3","number":"11.11.3","path":"11-tabapi-http-binding.html#tabresource-methods-7","title":"6.11.3 Resource methods"},"subsections":[{"section":{"id":"tabget-5","level":"4","number":"11.11.3.1","path":"11-tabapi-http-binding.html#tabget-5","title":"6.11.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-4","level":"4","number":"11.11.3.2","path":"11-tabapi-http-binding.html#tabpatch-4","title":"6.11.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-4","level":"4","number":"11.11.3.3","path":"11-tabapi-http-binding.html#tabdelete-4","title":"6.11.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptions","level":"2","number":"11.12","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptions","title":"6.12 Resource: csourceSubscriptions/"},"subsections":[{"section":{"id":"tabdescription-70","level":"3","number":"11.12.1","path":"11-tabapi-http-binding.html#tabdescription-70","title":"6.12.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-8","level":"3","number":"11.12.2","path":"11-tabapi-http-binding.html#tabresource-definition-8","title":"6.12.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-8","level":"3","number":"11.12.3","path":"11-tabapi-http-binding.html#tabresource-methods-8","title":"6.12.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-4","level":"4","number":"11.12.3.1","path":"11-tabapi-http-binding.html#tabpost-4","title":"6.12.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-6","level":"4","number":"11.12.3.2","path":"11-tabapi-http-binding.html#tabget-6","title":"6.12.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptionssubscriptionid","level":"2","number":"11.13","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptionssubscriptionid","title":"6.13 Resource: csourceSubscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-71","level":"3","number":"11.13.1","path":"11-tabapi-http-binding.html#tabdescription-71","title":"6.13.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-9","level":"3","number":"11.13.2","path":"11-tabapi-http-binding.html#tabresource-definition-9","title":"6.13.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-9","level":"3","number":"11.13.3","path":"11-tabapi-http-binding.html#tabresource-methods-9","title":"6.13.3 Resource methods"},"subsections":[{"section":{"id":"tabget-7","level":"4","number":"11.13.3.1","path":"11-tabapi-http-binding.html#tabget-7","title":"6.13.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-5","level":"4","number":"11.13.3.2","path":"11-tabapi-http-binding.html#tabpatch-5","title":"6.13.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-5","level":"4","number":"11.13.3.3","path":"11-tabapi-http-binding.html#tabdelete-5","title":"6.13.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationscreate","level":"2","number":"11.14","path":"11-tabapi-http-binding.html#tabresource-entityoperationscreate","title":"6.14 Resource: entityOperations/create"},"subsections":[{"section":{"id":"tabdescription-72","level":"3","number":"11.14.1","path":"11-tabapi-http-binding.html#tabdescription-72","title":"6.14.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-10","level":"3","number":"11.14.2","path":"11-tabapi-http-binding.html#tabresource-definition-10","title":"6.14.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-10","level":"3","number":"11.14.3","path":"11-tabapi-http-binding.html#tabresource-methods-10","title":"6.14.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-5","level":"4","number":"11.14.3.1","path":"11-tabapi-http-binding.html#tabpost-5","title":"6.14.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupsert","level":"2","number":"11.15","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupsert","title":"6.15 Resource: entityOperations/upsert"},"subsections":[{"section":{"id":"tabdescription-73","level":"3","number":"11.15.1","path":"11-tabapi-http-binding.html#tabdescription-73","title":"6.15.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-11","level":"3","number":"11.15.2","path":"11-tabapi-http-binding.html#tabresource-definition-11","title":"6.15.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-11","level":"3","number":"11.15.3","path":"11-tabapi-http-binding.html#tabresource-methods-11","title":"6.15.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-6","level":"4","number":"11.15.3.1","path":"11-tabapi-http-binding.html#tabpost-6","title":"6.15.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupdate","level":"2","number":"11.16","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupdate","title":"6.16 Resource: entityOperations/update"},"subsections":[{"section":{"id":"tabdescription-74","level":"3","number":"11.16.1","path":"11-tabapi-http-binding.html#tabdescription-74","title":"6.16.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-12","level":"3","number":"11.16.2","path":"11-tabapi-http-binding.html#tabresource-definition-12","title":"6.16.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-12","level":"3","number":"11.16.3","path":"11-tabapi-http-binding.html#tabresource-methods-12","title":"6.16.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-7","level":"4","number":"11.16.3.1","path":"11-tabapi-http-binding.html#tabpost-7","title":"6.16.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsdelete","level":"2","number":"11.17","path":"11-tabapi-http-binding.html#tabresource-entityoperationsdelete","title":"6.17 Resource: entityOperations/delete"},"subsections":[{"section":{"id":"tabdescription-75","level":"3","number":"11.17.1","path":"11-tabapi-http-binding.html#tabdescription-75","title":"6.17.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-13","level":"3","number":"11.17.2","path":"11-tabapi-http-binding.html#tabresource-definition-13","title":"6.17.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-13","level":"3","number":"11.17.3","path":"11-tabapi-http-binding.html#tabresource-methods-13","title":"6.17.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-8","level":"4","number":"11.17.3.1","path":"11-tabapi-http-binding.html#tabpost-8","title":"6.17.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentities","level":"2","number":"11.18","path":"11-tabapi-http-binding.html#tabresource-temporalentities","title":"6.18 Resource: temporal/entities/"},"subsections":[{"section":{"id":"tabdescription-76","level":"3","number":"11.18.1","path":"11-tabapi-http-binding.html#tabdescription-76","title":"6.18.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-14","level":"3","number":"11.18.2","path":"11-tabapi-http-binding.html#tabresource-definition-14","title":"6.18.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-14","level":"3","number":"11.18.3","path":"11-tabapi-http-binding.html#tabresource-methods-14","title":"6.18.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-9","level":"4","number":"11.18.3.1","path":"11-tabapi-http-binding.html#tabpost-9","title":"6.18.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-8","level":"4","number":"11.18.3.2","path":"11-tabapi-http-binding.html#tabget-8","title":"6.18.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityid","level":"2","number":"11.19","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityid","title":"6.19 Resource: temporal/entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-77","level":"3","number":"11.19.1","path":"11-tabapi-http-binding.html#tabdescription-77","title":"6.19.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-15","level":"3","number":"11.19.2","path":"11-tabapi-http-binding.html#tabresource-definition-15","title":"6.19.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-15","level":"3","number":"11.19.3","path":"11-tabapi-http-binding.html#tabresource-methods-15","title":"6.19.3 Resource methods"},"subsections":[{"section":{"id":"tabget-9","level":"4","number":"11.19.3.1","path":"11-tabapi-http-binding.html#tabget-9","title":"6.19.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-6","level":"4","number":"11.19.3.2","path":"11-tabapi-http-binding.html#tabdelete-6","title":"6.19.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrs","level":"2","number":"11.20","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrs","title":"6.20 Resource: temporal/entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-78","level":"3","number":"11.20.1","path":"11-tabapi-http-binding.html#tabdescription-78","title":"6.20.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-16","level":"3","number":"11.20.2","path":"11-tabapi-http-binding.html#tabresource-definition-16","title":"6.20.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-16","level":"3","number":"11.20.3","path":"11-tabapi-http-binding.html#tabresource-methods-16","title":"6.20.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-10","level":"4","number":"11.20.3.1","path":"11-tabapi-http-binding.html#tabpost-10","title":"6.20.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid","level":"2","number":"11.21","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid","title":"6.21 Resource: temporal/entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-79","level":"3","number":"11.21.1","path":"11-tabapi-http-binding.html#tabdescription-79","title":"6.21.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-17","level":"3","number":"11.21.2","path":"11-tabapi-http-binding.html#tabresource-definition-17","title":"6.21.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-17","level":"3","number":"11.21.3","path":"11-tabapi-http-binding.html#tabresource-methods-17","title":"6.21.3 Resource methods"},"subsections":[{"section":{"id":"tabdelete-7","level":"4","number":"11.21.3.1","path":"11-tabapi-http-binding.html#tabdelete-7","title":"6.21.3.1 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid-instanceid","level":"2","number":"11.22","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid-instanceid","title":"6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId}"},"subsections":[{"section":{"id":"tabdescription-80","level":"3","number":"11.22.1","path":"11-tabapi-http-binding.html#tabdescription-80","title":"6.22.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-18","level":"3","number":"11.22.2","path":"11-tabapi-http-binding.html#tabresource-definition-18","title":"6.22.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-18","level":"3","number":"11.22.3","path":"11-tabapi-http-binding.html#tabresource-methods-18","title":"6.22.3 Resource methods"},"subsections":[{"section":{"id":"tabpatch-6","level":"4","number":"11.22.3.1","path":"11-tabapi-http-binding.html#tabpatch-6","title":"6.22.3.1 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-8","level":"4","number":"11.22.3.2","path":"11-tabapi-http-binding.html#tabdelete-8","title":"6.22.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsquery","level":"2","number":"11.23","path":"11-tabapi-http-binding.html#tabresource-entityoperationsquery","title":"6.23 Resource: entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-81","level":"3","number":"11.23.1","path":"11-tabapi-http-binding.html#tabdescription-81","title":"6.23.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-19","level":"3","number":"11.23.2","path":"11-tabapi-http-binding.html#tabresource-definition-19","title":"6.23.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-19","level":"3","number":"11.23.3","path":"11-tabapi-http-binding.html#tabresource-methods-19","title":"6.23.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-11","level":"4","number":"11.23.3.1","path":"11-tabapi-http-binding.html#tabpost-11","title":"6.23.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentityoperationsquery","level":"2","number":"11.24","path":"11-tabapi-http-binding.html#tabresource-temporalentityoperationsquery","title":"6.24 Resource: temporal/entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-82","level":"3","number":"11.24.1","path":"11-tabapi-http-binding.html#tabdescription-82","title":"6.24.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-20","level":"3","number":"11.24.2","path":"11-tabapi-http-binding.html#tabresource-definition-20","title":"6.24.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-20","level":"3","number":"11.24.3","path":"11-tabapi-http-binding.html#tabresource-methods-20","title":"6.24.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-12","level":"4","number":"11.24.3.1","path":"11-tabapi-http-binding.html#tabpost-12","title":"6.24.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-types","level":"2","number":"11.25","path":"11-tabapi-http-binding.html#tabresource-types","title":"6.25 Resource: types/"},"subsections":[{"section":{"id":"tabdescription-83","level":"3","number":"11.25.1","path":"11-tabapi-http-binding.html#tabdescription-83","title":"6.25.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-21","level":"3","number":"11.25.2","path":"11-tabapi-http-binding.html#tabresource-definition-21","title":"6.25.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-21","level":"3","number":"11.25.3","path":"11-tabapi-http-binding.html#tabresource-methods-21","title":"6.25.3 Resource methods"},"subsections":[{"section":{"id":"tabget-10","level":"4","number":"11.25.3.1","path":"11-tabapi-http-binding.html#tabget-10","title":"6.25.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-typestype","level":"2","number":"11.26","path":"11-tabapi-http-binding.html#tabresource-typestype","title":"6.26 Resource: types/{type}"},"subsections":[{"section":{"id":"tabdescription-84","level":"3","number":"11.26.1","path":"11-tabapi-http-binding.html#tabdescription-84","title":"6.26.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-22","level":"3","number":"11.26.2","path":"11-tabapi-http-binding.html#tabresource-definition-22","title":"6.26.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-22","level":"3","number":"11.26.3","path":"11-tabapi-http-binding.html#tabresource-methods-22","title":"6.26.3 Resource methods"},"subsections":[{"section":{"id":"tabget-11","level":"4","number":"11.26.3.1","path":"11-tabapi-http-binding.html#tabget-11","title":"6.26.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributes","level":"2","number":"11.27","path":"11-tabapi-http-binding.html#tabresource-attributes","title":"6.27 Resource: attributes/"},"subsections":[{"section":{"id":"tabdescription-85","level":"3","number":"11.27.1","path":"11-tabapi-http-binding.html#tabdescription-85","title":"6.27.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-23","level":"3","number":"11.27.2","path":"11-tabapi-http-binding.html#tabresource-definition-23","title":"6.27.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-23","level":"3","number":"11.27.3","path":"11-tabapi-http-binding.html#tabresource-methods-23","title":"6.27.3 Resource methods"},"subsections":[{"section":{"id":"tabget-12","level":"4","number":"11.27.3.1","path":"11-tabapi-http-binding.html#tabget-12","title":"6.27.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributesattrid","level":"2","number":"11.28","path":"11-tabapi-http-binding.html#tabresource-attributesattrid","title":"6.28 Resource: attributes/{attrId}"},"subsections":[{"section":{"id":"tabdescription-86","level":"3","number":"11.28.1","path":"11-tabapi-http-binding.html#tabdescription-86","title":"6.28.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-24","level":"3","number":"11.28.2","path":"11-tabapi-http-binding.html#tabresource-definition-24","title":"6.28.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-24","level":"3","number":"11.28.3","path":"11-tabapi-http-binding.html#tabresource-methods-24","title":"6.28.3 Resource methods"},"subsections":[{"section":{"id":"tabget-13","level":"4","number":"11.28.3.1","path":"11-tabapi-http-binding.html#tabget-13","title":"6.28.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontexts","level":"2","number":"11.29","path":"11-tabapi-http-binding.html#tabresource-jsonldcontexts","title":"6.29 Resource: jsonldContexts/"},"subsections":[{"section":{"id":"tabdescription-87","level":"3","number":"11.29.1","path":"11-tabapi-http-binding.html#tabdescription-87","title":"6.29.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-25","level":"3","number":"11.29.2","path":"11-tabapi-http-binding.html#tabresource-definition-25","title":"6.29.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-25","level":"3","number":"11.29.3","path":"11-tabapi-http-binding.html#tabresource-methods-25","title":"6.29.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-13","level":"4","number":"11.29.3.1","path":"11-tabapi-http-binding.html#tabpost-13","title":"6.29.3.1 POST"},"subsections":[]},{"section":{"id":"tabget-14","level":"4","number":"11.29.3.2","path":"11-tabapi-http-binding.html#tabget-14","title":"6.29.3.2 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontextscontextid","level":"2","number":"11.30","path":"11-tabapi-http-binding.html#tabresource-jsonldcontextscontextid","title":"6.30 Resource: jsonldContexts/{contextId}"},"subsections":[{"section":{"id":"tabdescription-88","level":"3","number":"11.30.1","path":"11-tabapi-http-binding.html#tabdescription-88","title":"6.30.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-26","level":"3","number":"11.30.2","path":"11-tabapi-http-binding.html#tabresource-definition-26","title":"6.30.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-26","level":"3","number":"11.30.3","path":"11-tabapi-http-binding.html#tabresource-methods-26","title":"6.30.3 Resource methods"},"subsections":[{"section":{"id":"tabget-15","level":"4","number":"11.30.3.1","path":"11-tabapi-http-binding.html#tabget-15","title":"6.30.3.1 GET"},"subsections":[]},{"section":{"id":"tabdelete-9","level":"4","number":"11.30.3.2","path":"11-tabapi-http-binding.html#tabdelete-9","title":"6.30.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsmerge","level":"2","number":"11.31","path":"11-tabapi-http-binding.html#tabresource-entityoperationsmerge","title":"6.31 Resource: entityOperations/merge"},"subsections":[{"section":{"id":"tabdescription-89","level":"3","number":"11.31.1","path":"11-tabapi-http-binding.html#tabdescription-89","title":"6.31.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-27","level":"3","number":"11.31.2","path":"11-tabapi-http-binding.html#tabresource-definition-27","title":"6.31.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-27","level":"3","number":"11.31.3","path":"11-tabapi-http-binding.html#tabresource-methods-27","title":"6.31.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-14","level":"4","number":"11.31.3.1","path":"11-tabapi-http-binding.html#tabpost-14","title":"6.31.3.1 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitymapsentitymapid","level":"2","number":"11.32","path":"11-tabapi-http-binding.html#tabresource-entitymapsentitymapid","title":"6.32 Resource: entityMaps/{entityMapId}"},"subsections":[{"section":{"id":"tabdescription-90","level":"3","number":"11.32.1","path":"11-tabapi-http-binding.html#tabdescription-90","title":"6.32.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-28","level":"3","number":"11.32.2","path":"11-tabapi-http-binding.html#tabresource-definition-28","title":"6.32.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-28","level":"3","number":"11.32.3","path":"11-tabapi-http-binding.html#tabresource-methods-28","title":"6.32.3 Resource methods"},"subsections":[{"section":{"id":"tabget-16","level":"4","number":"11.32.3.1","path":"11-tabapi-http-binding.html#tabget-16","title":"6.32.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-7","level":"4","number":"11.32.3.2","path":"11-tabapi-http-binding.html#tabpatch-7","title":"6.32.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-10","level":"4","number":"11.32.3.3","path":"11-tabapi-http-binding.html#tabdelete-10","title":"6.32.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-infosourceidentity","level":"2","number":"11.33","path":"11-tabapi-http-binding.html#tabresource-infosourceidentity","title":"6.33 Resource: info/sourceIdentity"},"subsections":[{"section":{"id":"tabdescription-91","level":"3","number":"11.33.1","path":"11-tabapi-http-binding.html#tabdescription-91","title":"6.33.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-29","level":"3","number":"11.33.2","path":"11-tabapi-http-binding.html#tabresource-definition-29","title":"6.33.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-29","level":"3","number":"11.33.3","path":"11-tabapi-http-binding.html#tabresource-methods-29","title":"6.33.3 Resource methods"},"subsections":[{"section":{"id":"tabget-17","level":"4","number":"11.33.3.1","path":"11-tabapi-http-binding.html#tabget-17","title":"6.33.3.1 GET"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitymaps","level":"2","number":"11.34","path":"11-tabapi-http-binding.html#tabresource-entitymaps","title":"6.34 Resource: entityMaps"},"subsections":[{"section":{"id":"tabdescription-92","level":"3","number":"11.34.1","path":"11-tabapi-http-binding.html#tabdescription-92","title":"6.34.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-30","level":"3","number":"11.34.2","path":"11-tabapi-http-binding.html#tabresource-definition-30","title":"6.34.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-30","level":"3","number":"11.34.3","path":"11-tabapi-http-binding.html#tabresource-methods-30","title":"6.34.3 Resource methods"},"subsections":[{"section":{"id":"tabget-18","level":"4","number":"11.34.3.1","path":"11-tabapi-http-binding.html#tabget-18","title":"6.34.3.1 GET"},"subsections":[]},{"section":{"id":"tabpost-15","level":"4","number":"11.34.3.2","path":"11-tabapi-http-binding.html#tabpost-15","title":"6.34.3.2 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitymaps","level":"2","number":"11.35","path":"11-tabapi-http-binding.html#tabresource-temporalentitymaps","title":"6.35 Resource: temporal/entityMaps"},"subsections":[{"section":{"id":"tabdescription-93","level":"3","number":"11.35.1","path":"11-tabapi-http-binding.html#tabdescription-93","title":"6.35.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-31","level":"3","number":"11.35.2","path":"11-tabapi-http-binding.html#tabresource-definition-31","title":"6.35.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-31","level":"3","number":"11.35.3","path":"11-tabapi-http-binding.html#tabresource-methods-31","title":"6.35.3 Resource methods"},"subsections":[{"section":{"id":"tabget-19","level":"4","number":"11.35.3.1","path":"11-tabapi-http-binding.html#tabget-19","title":"6.35.3.1 GET"},"subsections":[]},{"section":{"id":"tabpost-16","level":"4","number":"11.35.3.2","path":"11-tabapi-http-binding.html#tabpost-16","title":"6.35.3.2 POST"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshots","level":"2","number":"11.36","path":"11-tabapi-http-binding.html#tabresource-snapshots","title":"6.36 Resource: snapshots"},"subsections":[{"section":{"id":"tabdescription-94","level":"3","number":"11.36.1","path":"11-tabapi-http-binding.html#tabdescription-94","title":"6.36.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-32","level":"3","number":"11.36.2","path":"11-tabapi-http-binding.html#tabresource-definition-32","title":"6.36.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-32","level":"3","number":"11.36.3","path":"11-tabapi-http-binding.html#tabresource-methods-32","title":"6.36.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-17","level":"4","number":"11.36.3.1","path":"11-tabapi-http-binding.html#tabpost-17","title":"6.36.3.1 POST"},"subsections":[]},{"section":{"id":"tabdelete-11","level":"4","number":"11.36.3.2","path":"11-tabapi-http-binding.html#tabdelete-11","title":"6.36.3.2 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshotssnapshotid","level":"2","number":"11.37","path":"11-tabapi-http-binding.html#tabresource-snapshotssnapshotid","title":"6.37 Resource: snapshots/{snapshotId}"},"subsections":[{"section":{"id":"tabdescription-95","level":"3","number":"11.37.1","path":"11-tabapi-http-binding.html#tabdescription-95","title":"6.37.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-33","level":"3","number":"11.37.2","path":"11-tabapi-http-binding.html#tabresource-definition-33","title":"6.37.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-33","level":"3","number":"11.37.3","path":"11-tabapi-http-binding.html#tabresource-methods-33","title":"6.37.3 Resource methods"},"subsections":[{"section":{"id":"tabget-20","level":"4","number":"11.37.3.1","path":"11-tabapi-http-binding.html#tabget-20","title":"6.37.3.1 GET"},"subsections":[]},{"section":{"id":"tabpatch-8","level":"4","number":"11.37.3.2","path":"11-tabapi-http-binding.html#tabpatch-8","title":"6.37.3.2 PATCH"},"subsections":[]},{"section":{"id":"tabdelete-12","level":"4","number":"11.37.3.3","path":"11-tabapi-http-binding.html#tabdelete-12","title":"6.37.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-snapshotssnapshotidclone","level":"2","number":"11.38","path":"11-tabapi-http-binding.html#tabresource-snapshotssnapshotidclone","title":"6.38 Resource: snapshots/{snapshotId}/clone"},"subsections":[{"section":{"id":"tabdescription-96","level":"3","number":"11.38.1","path":"11-tabapi-http-binding.html#tabdescription-96","title":"6.38.1 Description"},"subsections":[]},{"section":{"id":"tabresource-definition-34","level":"3","number":"11.38.2","path":"11-tabapi-http-binding.html#tabresource-definition-34","title":"6.38.2 Resource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-34","level":"3","number":"11.38.3","path":"11-tabapi-http-binding.html#tabresource-methods-34","title":"6.38.3 Resource methods"},"subsections":[{"section":{"id":"tabpost-18","level":"4","number":"11.38.3.1","path":"11-tabapi-http-binding.html#tabpost-18","title":"6.38.3.1 POST"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-mqtt-notification-binding","level":"1","number":"12","path":"12-tabapi-mqtt-notification-binding.html#tabapi-mqtt-notification-binding","title":"7 API MQTT Notification Binding"},"subsections":[{"section":{"id":"tabintroduction-23","level":"2","number":"12.1","path":"12-tabapi-mqtt-notification-binding.html#tabintroduction-23","title":"7.1 Introduction"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-3","level":"2","number":"12.2","path":"12-tabapi-mqtt-notification-binding.html#tabnotification-behaviour-3","title":"7.2 Notification behaviour"},"subsections":[]}]},{"section":{"id":"annex-a-normative-ngsi-ld-identifier-considerations","level":"1","number":"13","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#annex-a-normative-ngsi-ld-identifier-considerations","title":"Annex A (normative): NGSI-LD identifier considerations"},"subsections":[{"section":{"id":"a.1tabintroduction","level":"2","number":"13.1","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.1tabintroduction","title":"A.1 Introduction"},"subsections":[]},{"section":{"id":"a.2tabentity-identifiers","level":"2","number":"13.2","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.2tabentity-identifiers","title":"A.2 Entity identifiers"},"subsections":[]},{"section":{"id":"a.3tabngsi-ld-namespace","level":"2","number":"13.3","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.3tabngsi-ld-namespace","title":"A.3 NGSI-LD namespace"},"subsections":[]}]},{"section":{"id":"annex-b-normative-core-ngsi-ld-context-definition","level":"1","number":"14","path":"14-annex-b-normative-core-ngsi-ld-context-definition.html#annex-b-normative-core-ngsi-ld-context-definition","title":"Annex B (normative): Core NGSI-LD @context definition"},"subsections":[]},{"section":{"id":"annex-c-informative-examples-of-using-the-api","level":"1","number":"15","path":"15-annex-c-informative-examples-of-using-the-api.html#annex-c-informative-examples-of-using-the-api","title":"Annex C (informative): Examples of using the API"},"subsections":[{"section":{"id":"c.1tabintroduction","level":"2","number":"15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.1tabintroduction","title":"C.1 Introduction"},"subsections":[]},{"section":{"id":"c.2tabentity-representation","level":"2","number":"15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2tabentity-representation","title":"C.2 Entity Representation"},"subsections":[{"section":{"id":"c.2.1tabproperty-graph","level":"3","number":"15.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.1tabproperty-graph","title":"C.2.1 Property Graph"},"subsections":[]},{"section":{"id":"c.2.2tabvehicle-entity","level":"3","number":"15.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.2tabvehicle-entity","title":"C.2.2 Vehicle Entity"},"subsections":[]},{"section":{"id":"c.2.3tabparking-entity","level":"3","number":"15.2.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.3tabparking-entity","title":"C.2.3 Parking Entity"},"subsections":[]},{"section":{"id":"c.2.4tabcontext","level":"3","number":"15.2.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.4tabcontext","title":"C.2.4 @context"},"subsections":[]}]},{"section":{"id":"c.3tabcontext-source-registration","level":"2","number":"15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.3tabcontext-source-registration","title":"C.3 Context Source Registration"},"subsections":[]},{"section":{"id":"c.4tabcontext-subscription","level":"2","number":"15.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.4tabcontext-subscription","title":"C.4 Context Subscription"},"subsections":[]},{"section":{"id":"c.5tabhttp-rest-api-examples","level":"2","number":"15.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5tabhttp-rest-api-examples","title":"C.5 HTTP REST API Examples"},"subsections":[{"section":{"id":"c.5.1tabintroduction","level":"3","number":"15.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.1tabintroduction","title":"C.5.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.2tabcreate-entity-of-type-vehicle","level":"3","number":"15.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2tabcreate-entity-of-type-vehicle","title":"C.5.2 Create Entity of Type Vehicle"},"subsections":[{"section":{"id":"c.5.2.1tabhttp-request","level":"4","number":"15.5.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.1tabhttp-request","title":"C.5.2.1 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.2.2tabhttp-response","level":"4","number":"15.5.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.2tabhttp-response","title":"C.5.2.2 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.3tabquery-entities","level":"3","number":"15.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3tabquery-entities","title":"C.5.3 Query Entities"},"subsections":[{"section":{"id":"c.5.3.1tabintroduction","level":"4","number":"15.5.3.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.1tabintroduction","title":"C.5.3.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.3.2tabhttp-request","level":"4","number":"15.5.3.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.2tabhttp-request","title":"C.5.3.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.3.3tabhttp-response","level":"4","number":"15.5.3.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.3tabhttp-response","title":"C.5.3.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.4tabquery-entities-pagination","level":"3","number":"15.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4tabquery-entities-pagination","title":"C.5.4 Query Entities (Pagination)"},"subsections":[{"section":{"id":"c.5.4.1tabintroduction","level":"4","number":"15.5.4.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.1tabintroduction","title":"C.5.4.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.4.2tabhttp-request","level":"4","number":"15.5.4.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.2tabhttp-request","title":"C.5.4.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.4.3tabhttp-response","level":"4","number":"15.5.4.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.3tabhttp-response","title":"C.5.4.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.5tabtemporal-query","level":"3","number":"15.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5tabtemporal-query","title":"C.5.5 Temporal Query"},"subsections":[{"section":{"id":"c.5.5.1tabintroduction","level":"4","number":"15.5.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.1tabintroduction","title":"C.5.5.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.5.2tabhttp-request-1","level":"4","number":"15.5.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.2tabhttp-request-1","title":"C.5.5.2 HTTP Request #1"},"subsections":[]},{"section":{"id":"c.5.5.3tabhttp-response-1","level":"4","number":"15.5.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.3tabhttp-response-1","title":"C.5.5.3 HTTP Response #1"},"subsections":[]},{"section":{"id":"c.5.5.3tabhttp-request-2","level":"4","number":"15.5.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.3tabhttp-request-2","title":"C.5.5.3 HTTP Request #2"},"subsections":[]},{"section":{"id":"c.5.5.4tabhttp-response-2","level":"4","number":"15.5.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.4tabhttp-response-2","title":"C.5.5.4 HTTP Response #2"},"subsections":[]}]},{"section":{"id":"c.5.6tabtemporal-query-simplified-representation","level":"3","number":"15.5.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6tabtemporal-query-simplified-representation","title":"C.5.6 Temporal Query (Simplified Representation)"},"subsections":[{"section":{"id":"c.5.6.1tabintroduction","level":"4","number":"15.5.6.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.1tabintroduction","title":"C.5.6.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.6.2tabhttp-request","level":"4","number":"15.5.6.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.2tabhttp-request","title":"C.5.6.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.6.3tabhttp-response","level":"4","number":"15.5.6.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.3tabhttp-response","title":"C.5.6.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.7tabretrieve-available-entity-types","level":"3","number":"15.5.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7tabretrieve-available-entity-types","title":"C.5.7 Retrieve Available Entity Types"},"subsections":[{"section":{"id":"c.5.7.1tabintroduction","level":"4","number":"15.5.7.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.1tabintroduction","title":"C.5.7.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.7.2tabhttp-request","level":"4","number":"15.5.7.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.2tabhttp-request","title":"C.5.7.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.7.3tabhttp-response","level":"4","number":"15.5.7.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.3tabhttp-response","title":"C.5.7.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.8tabretrieve-details-of-available-entity-types","level":"3","number":"15.5.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8tabretrieve-details-of-available-entity-types","title":"C.5.8 Retrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"c.5.8.1tabintroduction","level":"4","number":"15.5.8.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.1tabintroduction","title":"C.5.8.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.8.2tabhttp-request","level":"4","number":"15.5.8.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.2tabhttp-request","title":"C.5.8.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.8.3tabhttp-response","level":"4","number":"15.5.8.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.3tabhttp-response","title":"C.5.8.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.9tabretrieve-available-entity-type-information","level":"3","number":"15.5.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9tabretrieve-available-entity-type-information","title":"C.5.9 Retrieve Available Entity Type Information"},"subsections":[{"section":{"id":"c.5.9.1tabintroduction","level":"4","number":"15.5.9.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.1tabintroduction","title":"C.5.9.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.9.2tabhttp-request","level":"4","number":"15.5.9.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.2tabhttp-request","title":"C.5.9.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.9.3tabhttp-response","level":"4","number":"15.5.9.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.3tabhttp-response","title":"C.5.9.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.10tabretrieve-available-attributes","level":"3","number":"15.5.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10tabretrieve-available-attributes","title":"C.5.10 Retrieve Available Attributes"},"subsections":[{"section":{"id":"c.5.10.1tabintroduction","level":"4","number":"15.5.10.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.1tabintroduction","title":"C.5.10.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.10.2tabhttp-request","level":"4","number":"15.5.10.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.2tabhttp-request","title":"C.5.10.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.10.3tabhttp-response","level":"4","number":"15.5.10.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.3tabhttp-response","title":"C.5.10.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.11tabretrieve-details-of-available-attributes","level":"3","number":"15.5.11","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11tabretrieve-details-of-available-attributes","title":"C.5.11 Retrieve Details of Available Attributes"},"subsections":[{"section":{"id":"c.5.11.1tabintroduction","level":"4","number":"15.5.11.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.1tabintroduction","title":"C.5.11.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.11.2tabhttp-request","level":"4","number":"15.5.11.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.2tabhttp-request","title":"C.5.11.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.11.3tabhttp-response","level":"4","number":"15.5.11.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.3tabhttp-response","title":"C.5.11.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.12tabretrieve-available-attribute-information","level":"3","number":"15.5.12","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12tabretrieve-available-attribute-information","title":"C.5.12 Retrieve Available Attribute Information"},"subsections":[{"section":{"id":"c.5.12.1tabintroduction","level":"4","number":"15.5.12.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.1tabintroduction","title":"C.5.12.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.12.2tabhttp-request","level":"4","number":"15.5.12.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.2tabhttp-request","title":"C.5.12.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.12.3tabhttp-response","level":"4","number":"15.5.12.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.3tabhttp-response","title":"C.5.12.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.13tabquery-entities-natural-language-filtering","level":"3","number":"15.5.13","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13tabquery-entities-natural-language-filtering","title":"C.5.13 Query Entities (Natural Language Filtering)"},"subsections":[{"section":{"id":"c.5.13.1tabintroduction","level":"4","number":"15.5.13.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.1tabintroduction","title":"C.5.13.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.13.2tabhttp-request","level":"4","number":"15.5.13.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.2tabhttp-request","title":"C.5.13.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.13.3tabhttp-response","level":"4","number":"15.5.13.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.3tabhttp-response","title":"C.5.13.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.14tabtemporal-query-aggregated-representation","level":"3","number":"15.5.14","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14tabtemporal-query-aggregated-representation","title":"C.5.14 Temporal Query (Aggregated Representation)"},"subsections":[{"section":{"id":"c.5.14.1tabintroduction","level":"4","number":"15.5.14.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.1tabintroduction","title":"C.5.14.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.14.2tabhttp-request","level":"4","number":"15.5.14.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.2tabhttp-request","title":"C.5.14.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.14.3tabhttp-response","level":"4","number":"15.5.14.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.3tabhttp-response","title":"C.5.14.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.15tabscope-queries","level":"3","number":"15.5.15","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15tabscope-queries","title":"C.5.15 Scope Queries"},"subsections":[{"section":{"id":"c.5.15.1tabintroduction","level":"4","number":"15.5.15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.1tabintroduction","title":"C.5.15.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.15.2tabhttp-request","level":"4","number":"15.5.15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.2tabhttp-request","title":"C.5.15.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.15.3tabhttp-response","level":"4","number":"15.5.15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.3tabhttp-response","title":"C.5.15.3 HTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.16tabtemporal-scope-queries","level":"3","number":"15.5.16","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16tabtemporal-scope-queries","title":"C.5.16 Temporal Scope Queries"},"subsections":[{"section":{"id":"c.5.16.1tabintroduction","level":"4","number":"15.5.16.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.1tabintroduction","title":"C.5.16.1 Introduction"},"subsections":[]},{"section":{"id":"c.5.16.2tabhttp-request","level":"4","number":"15.5.16.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.2tabhttp-request","title":"C.5.16.2 HTTP Request"},"subsections":[]},{"section":{"id":"c.5.16.3tabhttp-response","level":"4","number":"15.5.16.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.3tabhttp-response","title":"C.5.16.3 HTTP Response"},"subsections":[]}]}]},{"section":{"id":"c.6tabdate-representation","level":"2","number":"15.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.6tabdate-representation","title":"C.6 Date Representation"},"subsections":[]},{"section":{"id":"c.7tabcontext-utilization-clarifications","level":"2","number":"15.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.7tabcontext-utilization-clarifications","title":"C.7 @context utilization clarifications"},"subsections":[]},{"section":{"id":"c.8tablink-header-utilization-clarifications","level":"2","number":"15.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.8tablink-header-utilization-clarifications","title":"C.8 Link header utilization clarifications"},"subsections":[]},{"section":{"id":"c.9tabcontext-processing-clarifications","level":"2","number":"15.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.9tabcontext-processing-clarifications","title":"C.9 @context processing clarifications"},"subsections":[]},{"section":{"id":"c.10tabvaluetype-datatype-utilization-clarifications","level":"2","number":"15.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.10tabvaluetype-datatype-utilization-clarifications","title":"C.10 ValueType datatype utilization clarifications"},"subsections":[]},{"section":{"id":"c.11tabentity-with-digital-signature-for-a-property","level":"2","number":"15.11","path":"15-annex-c-informative-examples-of-using-the-api.html#c.11tabentity-with-digital-signature-for-a-property","title":"C.11 Entity with digital signature for a Property"},"subsections":[]}]},{"section":{"id":"annex-d-informative-transformation-algorithms","level":"1","number":"16","path":"16-annex-d-informative-transformation-algorithms.html#annex-d-informative-transformation-algorithms","title":"Annex D (informative): Transformation Algorithms"},"subsections":[{"section":{"id":"d.1tabintroduction","level":"2","number":"16.1","path":"16-annex-d-informative-transformation-algorithms.html#d.1tabintroduction","title":"D.1 Introduction"},"subsections":[]},{"section":{"id":"d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","level":"2","number":"16.2","path":"16-annex-d-informative-transformation-algorithms.html#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","title":"D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)"},"subsections":[]},{"section":{"id":"d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","level":"2","number":"16.3","path":"16-annex-d-informative-transformation-algorithms.html#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","title":"D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1)"},"subsections":[]},{"section":{"id":"d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","level":"2","number":"16.4","path":"16-annex-d-informative-transformation-algorithms.html#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","title":"D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2)"},"subsections":[]}]},{"section":{"id":"annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","level":"1","number":"17","path":"17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","title":"Annex E (informative): RDF-compatible specification of NGSI-LD meta-model"},"subsections":[]},{"section":{"id":"annex-f-informative-conventions-and-syntax-guidelines","level":"1","number":"18","path":"18-annex-f-informative-conventions-and-syntax-guidelines.html#annex-f-informative-conventions-and-syntax-guidelines","title":"Annex F (informative): Conventions and syntax guidelines"},"subsections":[]},{"section":{"id":"annex-g-informative-localization-and-internationalization-support","level":"1","number":"19","path":"19-annex-g-informative-localization-and-internationalization-support.html#annex-g-informative-localization-and-internationalization-support","title":"Annex G (informative): Localization and Internationalization Support"},"subsections":[{"section":{"id":"g.0tabforeword","level":"2","number":"19.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.0tabforeword","title":"G.0 Foreword"},"subsections":[]},{"section":{"id":"g.1tabintroduction","level":"2","number":"19.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1tabintroduction","title":"G.1 Introduction"},"subsections":[{"section":{"id":"g.1.0tabforeword","level":"3","number":"19.2.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.0tabforeword","title":"G.1.0 Foreword"},"subsections":[]},{"section":{"id":"g.1.1tabassociating-an-entity-with-a-natural-language","level":"3","number":"19.2.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.1tabassociating-an-entity-with-a-natural-language","title":"G.1.1 Associating an Entity with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.2tabassociating-a-property-with-a-natural-language","level":"3","number":"19.2.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.2tabassociating-a-property-with-a-natural-language","title":"G.1.2 Associating a Property with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.3tabassociating-as-equivalent-entity","level":"3","number":"19.2.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.3tabassociating-as-equivalent-entity","title":"G.1.3 Associating as equivalent entity"},"subsections":[]}]},{"section":{"id":"g.2tabnatural-language-collation-support","level":"2","number":"19.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2tabnatural-language-collation-support","title":"G.2 Natural Language Collation Support"},"subsections":[{"section":{"id":"g.2.0tabforeword","level":"3","number":"19.3.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.0tabforeword","title":"G.2.0 Foreword"},"subsections":[]},{"section":{"id":"g.2.1tabmaintain-collations-as-metadata","level":"3","number":"19.3.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.1tabmaintain-collations-as-metadata","title":"G.2.1 Maintain collations as metadata"},"subsections":[]},{"section":{"id":"g.2.2tabroute-language-sensitive-queries-via-a-proxy","level":"3","number":"19.3.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.2tabroute-language-sensitive-queries-via-a-proxy","title":"G.2.2 Route language sensitive queries via a proxy"},"subsections":[]}]},{"section":{"id":"g.3tablocalization-of-dates-currency-formats-etc.","level":"2","number":"19.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3tablocalization-of-dates-currency-formats-etc.","title":"G.3 Localization of Dates, Currency formats, etc."},"subsections":[{"section":{"id":"g.3.0tabforeword","level":"3","number":"19.4.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.0tabforeword","title":"G.3.0 Foreword"},"subsections":[]},{"section":{"id":"g.3.1tablocalizing-dates","level":"3","number":"19.4.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.1tablocalizing-dates","title":"G.3.1 Localizing Dates"},"subsections":[]}]}]},{"section":{"id":"annex-h-informative-suggested-actuation-workflows","level":"1","number":"20","path":"20-annex-h-informative-suggested-actuation-workflows.html#annex-h-informative-suggested-actuation-workflows","title":"Annex H (informative): Suggested actuation workflows"},"subsections":[{"section":{"id":"h.1tabactuators-and-feedback-to-the-consumer","level":"2","number":"20.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.1tabactuators-and-feedback-to-the-consumer","title":"H.1 Actuators and feedback to the consumer"},"subsections":[]},{"section":{"id":"h.2tabarchitecture-for-actuation","level":"2","number":"20.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.2tabarchitecture-for-actuation","title":"H.2 Architecture for actuation"},"subsections":[]},{"section":{"id":"h.3tabstructure-of-commands-and-additional-properties","level":"2","number":"20.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3tabstructure-of-commands-and-additional-properties","title":"H.3 Structure of Commands and additional Properties"},"subsections":[{"section":{"id":"h.3.0tabintroduction","level":"3","number":"20.3.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.0tabintroduction","title":"H.3.0 Introduction"},"subsections":[]},{"section":{"id":"h.3.1tabproperty-for-listing-available-commands","level":"3","number":"20.3.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.1tabproperty-for-listing-available-commands","title":"H.3.1 Property for listing available commands"},"subsections":[]},{"section":{"id":"h.3.2tabproperties-for-command-endpoints","level":"3","number":"20.3.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.2tabproperties-for-command-endpoints","title":"H.3.2 Properties for command endpoints"},"subsections":[]}]},{"section":{"id":"h.4tabcommunication-model","level":"2","number":"20.4","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4tabcommunication-model","title":"H.4 Communication model"},"subsections":[{"section":{"id":"h.4.1tabpossible-communication-models","level":"3","number":"20.4.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.1tabpossible-communication-models","title":"H.4.1 Possible communication models"},"subsections":[]},{"section":{"id":"h.4.2tabsubscriptionnotification-model","level":"3","number":"20.4.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.2tabsubscriptionnotification-model","title":"H.4.2 Subscription/notification model"},"subsections":[]},{"section":{"id":"h.4.3tabforwarding-model","level":"3","number":"20.4.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.3tabforwarding-model","title":"H.4.3 Forwarding model"},"subsections":[]}]},{"section":{"id":"h.5tabimplementation-of-the-subscription-based-actuation-workflow","level":"2","number":"20.5","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.5tabimplementation-of-the-subscription-based-actuation-workflow","title":"H.5 Implementation of the subscription-based actuation workflow"},"subsections":[]},{"section":{"id":"h.6tabimplementation-of-the-registration-based-actuation-workflow","level":"2","number":"20.6","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.6tabimplementation-of-the-registration-based-actuation-workflow","title":"H.6 Implementation of the registration-based actuation workflow"},"subsections":[]}]},{"section":{"id":"annex-i-informative-change-history","level":"1","number":"21","path":"21-annex-i-informative-change-history.html#annex-i-informative-change-history","title":"Annex I (informative): Change history"},"subsections":[]},{"section":{"id":"history","level":"1","number":"22","path":"22-history.html#history","title":"History"},"subsections":[]}]} \ No newline at end of file diff --git a/API/styles.css b/API/styles.css deleted file mode 100644 index d47da90e0d65d273506a95f69c905db01ee39da3..0000000000000000000000000000000000000000 --- a/API/styles.css +++ /dev/null @@ -1,415 +0,0 @@ -.NF { - font-family: Arial; - font-size: 9pt; - align-items: center; - display: flex; - gap: 4pt; -} - -.TAH { - font-family: Arial; - font-size: 9pt; - font-weight: bold; - text-align: center; -} - -.TAC { - font-family: Arial; - font-size: 9pt; - text-align: center; -} - -.TAL { - font-family: Arial; - font-size: 9pt; -} - -.ondemand_CHAR_name_Arial_size_9 { - font-family: Arial; - font-size: 9pt; -} - -.HTML_Variable { - font-family: "Roboto Mono", Monospace; - font-size: 8pt; - font-style: italic; -} - -.HTML_Keyboard { - font-family: Times New Roman; - font-size: 10pt; - color: #595959; -} - -.HTML_Definition { - font-style: italic; -} - -.TAN { - font-family: Arial; - font-size: 9pt; - padding-left: 12pt; - display: flex; - gap: 12pt; -} - -.HTML_Code { - font-family: "Roboto Mono", Monospace; - font-size: 8pt; - color: #31849b; -} - -.ondemand_CHAR_size_9 { - font-size: 9pt; -} - -.ondemand_CHAR_name_Roboto_Mono_size_8_color_31849B { - font-family: "Roboto Mono", Monospace; - font-size: 8pt; - color: #31849b; -} - -.ondemand_CHAR_size_9_color_000000 { - font-size: 9pt; - color: #000000; -} - -.ondemand_CHAR_color_000000 { - color: #000000; -} - -.Plain_Text_Char { - font-family: Courier New; -} - -.ondemand_CHAR_name_Roboto_Mono_size_8 { - font-family: "Roboto Mono", Monospace; - font-size: 8pt; - font-style: italic; -} - -.ondemand_CHAR_name_Courier_New { - font-family: Courier New; -} - -.ondemand_PAR_alignment_CENTER { - text-align: center; -} - -.HTML_Error { - font-family: Times New Roman; - font-weight: bold; - font-style: italic; - color: #595959; -} - -.TAJ { - font-family: Arial; - font-size: 9pt; - text-align: justify; -} - -.ondemand_CHAR_color_595959 { - color: #595959; -} - -.ondemand_PAR_alignment_CENTER_space_before_3_space_after_3 { - text-align: center; - margin-top: 3pt; - margin-bottom: 3pt; -} - -.FP { -} - -.ZA { - font-family: Arial; - font-size: 20pt; - text-align: right; -} - -.ondemand_CHAR_size_32 { - font-size: 32pt; -} - -.ZGSM { -} - -.ondemand_CHAR_size_16 { - font-size: 16pt; -} - -.ZT { - font-family: Arial; - font-size: 17pt; - font-weight: bold; - text-align: center; -} - -.ZG { - font-family: Arial; - text-align: right; -} - -.ZB { - font-family: Arial; - font-style: italic; - text-align: right; - font-family: Century Gothic; - font-size: 16pt; - font-weight: bold; - color: #ffffff; -} - -.ondemand_CHAR_name_Arial { - font-family: Arial; - font-weight: bold; - font-style: italic; -} - -.ondemand_CHAR_name_Century_Gothic_size_16_color_FFFFFF { - font-family: Century Gothic; - font-size: 16pt; - font-weight: bold; - color: #ffffff; -} - -.ondemand_CHAR_name_Arial_size_7 { - font-family: Arial; - font-size: 7pt; -} - -.H6 { - font-family: Arial; - font-size: 10pt; - margin-top: 6pt; - margin-bottom: 9pt; -} - -.ondemand_CHAR_size_8 { - font-size: 8pt; -} - -.NO { - padding-left: 12pt; - margin-bottom: 9pt; - display: flex; - gap: 12pt; -} - -.NO > p { - margin: 0; - padding: 0; - white-space: pre-wrap; -} - -.NO > p:first-of-type { - white-space: nowrap; -} - -.EX { - padding-left: 12pt; - margin-bottom: 9pt; - display: flex; - gap: 12pt; - align-items: flex-start; -} - -.EX > p { - margin: 0; - padding: 0; - white-space: pre-wrap; -} - -.EX > p:first-of-type { - white-space: nowrap; -} - -.ondemand_CHAR_color_0000FF { - color: #0000ff; -} - -.EW { - gap: 12pt; - display: flex; - align-items: flex-start; -} - -.EW > div:first-child { - min-width: 100px; - flex-shrink: 0; -} - -.EW > div:last-child { - flex: 1 -} - -.FL { - font-family: Arial; - font-weight: bold; - text-align: center; - margin-top: 3pt; - margin-bottom: 9pt; -} - -.TF { - font-family: Arial; - font-weight: bold; - text-align: center; - margin-bottom: 12pt; -} - -.B1plus { - margin-bottom: 9pt; -} - -.ondemand_PAR_space_after_12 { - margin-bottom: 12pt; -} - -.TH { - font-family: Arial; - font-weight: bold; - text-align: center; - margin-top: 3pt; - margin-bottom: 9pt; -} - -.ondemand_PAR_space_after_6 { - margin-bottom: 6pt; -} - -.ondemand_PAR_space_after_10 { - margin-bottom: 10pt; -} - -.B2plus { - margin-bottom: 9pt; -} - -.ondemand_CHAR_size_6 { - font-size: 6pt; -} - -.HTML_Sample { - font-family: Courier New; - font-size: 8pt; -} - -.ondemand_PAR_left_indent_14 { -} - -.ondemand_PAR_first_line_indent_14 { -} - -.ondemand_PAR_first_line_indent_-21_left_indent_35 { -} - -.B3 { - margin-bottom: 9pt; -} - -.ondemand_CHAR_name_Courier_New_size_9 { - font-family: Courier New; - font-size: 9pt; -} - -.B1 { - margin-bottom: 9pt; -} - -.PL { - font-family: Courier New; - font-size: 8pt; -} - -.ondemand_CHAR_name_Courier_New_size_8 { - font-family: Courier New; - font-size: 8pt; -} - -.Hyperlink { - text-decoration: underline; - color: #0000ff; -} - -.B3plus { - margin-bottom: 9pt; -} - -.ondemand_PAR_first_line_indent_-17_left_indent_35 { -} - -.author-a-g2z71zwz82zz83zlz72z32e6kez86zz76z { -} - -.ondemand_PAR_first_line_indent_-70_left_indent_70_space_before_6 { - margin-top: 6pt; -} - -.ondemand_CHAR_name_Arial_size_12 { - font-family: Arial; - font-size: 12pt; -} - -.B4 { - margin-bottom: 9pt; -} - -.B2 { - margin-bottom: 9pt; -} - -.ondemand_PAR_first_line_indent_-56_left_indent_56 { -} - -.B5 { - margin-bottom: 9pt; -} - -.ondemand_PAR_first_line_indent_-22_left_indent_59 { -} - -.ondemand_PAR_first_line_indent_-17_left_indent_71 { -} - -.BL { - margin-bottom: 9pt; -} - -.ondemand_PAR_left_indent_59_space_after_12 { - margin-bottom: 12pt; -} - -.ondemand_PAR_alignment_CENTER_space_before_3 { - text-align: center; - margin-top: 3pt; -} - -.ondemand_CHAR_size_12_color_000000 { - font-size: 12pt; - color: #000000; -} - -.example-title { -} - -.ondemand_PAR_alignment_CENTER_space_after_12 { - text-align: center; - margin-bottom: 12pt; -} - -.ondemand_PAR_left_indent_19 { -} - -.ondemand_PAR_space_after_3 { - margin-bottom: 3pt; -} - -.BN { - margin-bottom: 9pt; -} - -.image_overlay { - visibility: hidden; -} diff --git a/API/styling.css b/API/styling.css deleted file mode 100644 index 231f0ba2314851000020cbc7f785a8de6976840f..0000000000000000000000000000000000000000 --- a/API/styling.css +++ /dev/null @@ -1,1045 +0,0 @@ -/*! normalize.css v3.0.1 | MIT License | git.io/normalize */ - -/** -* 1. Set default font family to sans-serif. -* 2. Prevent iOS text size adjust after orientation change, without disabling -* user zoom. -*/ - -html { - font-family: sans-serif; /* 1 */ - -ms-text-size-adjust: 100%; /* 2 */ - -webkit-text-size-adjust: 100%; /* 2 */ -} - -/** - * Remove default margin. - */ - -body { - margin: 0; -} - -#TOC { - top: 0; - left: 0; - height: 100%; - width: unset; - position: relative; - - background-color: rgba(100, 100, 100, 0.6); - overflow-y: auto; - scrollbar-width: none; - -ms-overflow-style: none; -} - -#TOC a { - text-decoration: none; - font-size: 16px; - color: black; - display: block; - white-space: nowrap; /* Prevents text from wrapping */ - overflow: hidden; /* Hides overflow content */ - text-overflow: ellipsis; -} - -#editor { - padding: 0 2rem; -} - -@media screen and (max-width: 600px) { - #TOC { - width: 100%; - left: -100%; - } -} - -/* BORROWED FROM HERE: https://stackoverflow.com/questions/28767221/flexbox-resizing */ - -flex { - display: flex; - overflow: hidden; -} - -flex.h { - flex-direction: row; -} - -flex.v { - flex-direction: column; -} - -flex-item { - overflow: auto; -} - -flex > flex-resizer { - flex: 0 0 10px; - /* background: white; */ - background-color: #aaa; - background-repeat: no-repeat; - background-position: center; -} - -flex.h > flex-resizer { - cursor: ew-resize; - background-image: url("data:image/svg+xml;utf8,"); -} - -flex.v > flex-resizer { - cursor: ns-resize; - background-image: url("data:image/svg+xml;utf8,"); -} - -/* HTML5 display definitions - ========================================================================== */ - -/** - * Correct `block` display not defined for any HTML5 element in IE 8/9. - * Correct `block` display not defined for `details` or `summary` in IE 10/11 and Firefox. - * Correct `block` display not defined for `main` in IE 11. - */ - -article, -aside, -details, -figcaption, -figure, -footer, -header, -hgroup, -main, -nav, -section, -summary { - display: block; -} - -/** - * 1. Correct `inline-block` display not defined in IE 8/9. - * 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera. - */ - -audio, -canvas, -progress, -video { - display: inline-block; /* 1 */ - vertical-align: baseline; /* 2 */ -} - -/** - * Prevent modern browsers from displaying `audio` without controls. - * Remove excess height in iOS 5 devices. - */ - -audio:not([controls]) { - display: none; - height: 0; -} - -/** - * Address `[hidden]` styling not present in IE 8/9/10. - * Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22. - */ - -[hidden], -template { - display: none; -} - -/* Links - ========================================================================== */ - -/** - * Remove the gray background color from active links in IE 10. - */ - -a { - background: transparent; -} - -/** - * Improve readability when focused and also mouse hovered in all browsers. - */ - -a:active, -a:hover { - outline: 0; -} - -/* Text-level semantics - ========================================================================== */ - -/** - * Address styling not present in IE 8/9/10/11, Safari, and Chrome. - */ - -abbr[title] { - border-bottom: 1px dotted; -} - -/** - * Address style set to `bolder` in Firefox 4+, Safari, and Chrome. - */ - -b, -strong { - font-weight: bold; -} - -/** - * Address styling not present in Safari and Chrome. - */ - -dfn { - font-style: italic; -} - -/** - * Address variable `h1` font-size and margin within `section` and `article` - * contexts in Firefox 4+, Safari, and Chrome. - */ - -h1 { - font-size: 2em; - margin: 0.67em 0; -} - -/** - * Address styling not present in IE 8/9. - */ - -mark { - background: #ff0; - color: #000; -} - -/** - * Address inconsistent and variable font size in all browsers. - */ - -small { - font-size: 80%; -} - -/** - * Prevent `sub` and `sup` affecting `line-height` in all browsers. - */ - -sub, -sup { - font-size: 75%; - line-height: 0; - position: relative; - vertical-align: baseline; -} - -sup { - top: -0.5em; -} - -sub { - bottom: -0.25em; -} - -/* Embedded content - ========================================================================== */ - -/** - * Remove border when inside `a` element in IE 8/9/10. - */ - -img { - border: 0; -} - -/** - * Correct overflow not hidden in IE 9/10/11. - */ - -svg:not(:root) { - overflow: hidden; -} - -/* Grouping content - ========================================================================== */ - -/** - * Address margin not present in IE 8/9 and Safari. - */ - -figure { - margin: 1em 40px; -} - -/** - * Address differences between Firefox and other browsers. - */ - -hr { - -moz-box-sizing: content-box; - box-sizing: content-box; - height: 0; -} - -/** - * Contain overflow in all browsers. - */ - -pre { - overflow: auto; -} - -/** - * Address odd `em`-unit font size rendering in all browsers. - */ - -code, -kbd, -pre, -samp { - font-family: monospace, monospace; - font-size: 1em; -} - -/* Forms - ========================================================================== */ - -/** - * Known limitation: by default, Chrome and Safari on OS X allow very limited - * styling of `select`, unless a `border` property is set. - */ - -/** - * 1. Correct color not being inherited. - * Known issue: affects color of disabled elements. - * 2. Correct font properties not being inherited. - * 3. Address margins set differently in Firefox 4+, Safari, and Chrome. - */ - -button, -input, -optgroup, -select, -textarea { - color: inherit; /* 1 */ - font: inherit; /* 2 */ - margin: 0; /* 3 */ -} - -/** - * Address `overflow` set to `hidden` in IE 8/9/10/11. - */ - -button { - overflow: visible; -} - -/** - * Address inconsistent `text-transform` inheritance for `button` and `select`. - * All other form control elements do not inherit `text-transform` values. - * Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera. - * Correct `select` style inheritance in Firefox. - */ - -button, -select { - text-transform: none; -} - -/** - * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` - * and `video` controls. - * 2. Correct inability to style clickable `input` types in iOS. - * 3. Improve usability and consistency of cursor style between image-type - * `input` and others. - */ - -button, - html input[type="button"], /* 1 */ - input[type="reset"], - input[type="submit"] { - -webkit-appearance: button; /* 2 */ - cursor: pointer; /* 3 */ -} - -/** - * Re-set default cursor for disabled elements. - */ - -button[disabled], -html input[disabled] { - cursor: default; -} - -/** - * Remove inner padding and border in Firefox 4+. - */ - -button::-moz-focus-inner, -input::-moz-focus-inner { - border: 0; - padding: 0; -} - -/** - * Address Firefox 4+ setting `line-height` on `input` using `!important` in - * the UA stylesheet. - */ - -input { - line-height: normal; -} - -/** - * It's recommended that you don't attempt to style these elements. - * Firefox's implementation doesn't respect box-sizing, padding, or width. - * - * 1. Address box sizing set to `content-box` in IE 8/9/10. - * 2. Remove excess padding in IE 8/9/10. - */ - -input[type="checkbox"], -input[type="radio"] { - box-sizing: border-box; /* 1 */ - padding: 0; /* 2 */ -} - -/** - * Fix the cursor style for Chrome's increment/decrement buttons. For certain - * `font-size` values of the `input`, it causes the cursor style of the - * decrement button to change from `default` to `text`. - */ - -input[type="number"]::-webkit-inner-spin-button, -input[type="number"]::-webkit-outer-spin-button { - height: auto; -} - -/** - * 1. Address `appearance` set to `searchfield` in Safari and Chrome. - * 2. Address `box-sizing` set to `border-box` in Safari and Chrome - * (include `-moz` to future-proof). - */ - -input[type="search"] { - -webkit-appearance: textfield; /* 1 */ - -moz-box-sizing: content-box; - -webkit-box-sizing: content-box; /* 2 */ - box-sizing: content-box; -} - -/** - * Remove inner padding and search cancel button in Safari and Chrome on OS X. - * Safari (but not Chrome) clips the cancel button when the search input has - * padding (and `textfield` appearance). - */ - -input[type="search"]::-webkit-search-cancel-button, -input[type="search"]::-webkit-search-decoration { - -webkit-appearance: none; -} - -/** - * Define consistent border, margin, and padding. - */ - -fieldset { - border: 1px solid #c0c0c0; - margin: 0 2px; - padding: 0.35em 0.625em 0.75em; -} - -/** - * 1. Correct `color` not being inherited in IE 8/9/10/11. - * 2. Remove padding so people aren't caught out if they zero out fieldsets. - */ - -legend { - border: 0; /* 1 */ - padding: 0; /* 2 */ -} - -/** - * Remove default vertical scrollbar in IE 8/9/10/11. - */ - -textarea { - overflow: auto; -} - -/** - * Don't inherit the `font-weight` (applied by a rule above). - * NOTE: the default cannot safely be changed in Chrome and Safari on OS X. - */ - -optgroup { - font-weight: bold; -} - -/* Tables - ========================================================================== */ - -/** - * Remove most spacing between table cells. - */ - -table { - border-collapse: collapse; - border-spacing: 0; -} - -td, -th { - padding: 0; -} - -/* Figure captions */ - -.caption { - margin-bottom: 5em; -} - -/*! End of normalize.css - ========================================================================== */ - -/* Github styles - ========================================================================== */ - -* { - box-sizing: border-box; -} -body { - font-family: -apple-system, BlinkMacSystemFont, "Times New Roman", "Segoe UI", - Roboto, "Helvetica Neue", Helvetica, Arial, sans-serif, "Apple Color Emoji", - "Segoe UI Emoji", "Segoe UI Symbol"; - font-size: 10pt; - line-height: 1.6; - /* margin: auto; */ - /* max-width: 920px; - min-width: 360px; */ - max-width: 75%; - left: 275px; - position: relative; - padding: 2rem; - word-wrap: break-word; -} - -/* Headers - ========================================================================== */ - -h1, -h2, -h3, -h4, -h5, -h6 { - font-weight: 600; - line-height: 1.25; - margin-bottom: 16px; - margin-top: 24px; -} -h1 { - padding-bottom: 0.3em; - font-size: 2em; - border-bottom: 1px solid #eee; -} -h2 { - padding-bottom: 0.3em; - font-size: 1.5em; - border-bottom: 1px solid #eee; -} -h3 { - font-size: 1.25em; -} -h4 { - font-size: 1em; -} -h5 { - font-size: 0.875em; -} -h6 { - font-size: 0.85em; - color: #777; -} -h1 tt, -h1 code, -h2 tt, -h2 code, -h3 tt, -h3 code, -h4 tt, -h4 code, -h5 tt, -h5 code, -h6 tt, -h6 code { - font-size: inherit; -} -body > h2:first-child { - margin-top: 0; - padding-top: 0; -} -body > h1:first-child { - margin-top: 0; - padding-top: 0; -} -body > h1:first-child + h2 { - margin-top: 0; - padding-top: 0; -} -body > h3:first-child, -body > h4:first-child, -body > h5:first-child, -body > h6:first-child { - margin-top: 0; - padding-top: 0; -} -a:first-child h1, -a:first-child h2, -a:first-child h3, -a:first-child h4, -a:first-child h5, -a:first-child h6 { - margin-top: 0; - padding-top: 0; -} - -/* Flow Content - ========================================================================== */ - -a { - color: #4078c0; - text-decoration: none; -} -a:active, -a:hover { - outline: 0; - text-decoration: underline; -} -sup, -sub, -a.footnote { - font-size: 75%; - line-height: 0; - position: relative; - vertical-align: baseline; -} -sub { - bottom: -0.25em; -} -sup { - top: -0.5em; -} - -/* Block Content - ========================================================================== */ - -ol, -ul { - margin-bottom: 16px; - margin-top: 0; - padding-left: 2em; -} -p, -blockquote, -table, -pre { - margin: 15px 0; -} -ul, -ol { - padding-left: 2em; -} -ul.no-list, -ol.no-list { - padding: 0; - list-style-type: none; -} -ul ul, -ul ol, -ol ol, -ol ul { - margin-top: 0; - margin-bottom: 0; -} -li > p { - margin-top: 16px; -} -li + li { - margin-top: 0.25em; -} -ol li ul:first-of-type { - margin-top: 0; -} -hr { - background: transparent - url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAYAAAAECAYAAACtBE5DAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OENDRjNBN0E2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OENDRjNBN0I2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo4Q0NGM0E3ODY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo4Q0NGM0E3OTY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PqqezsUAAAAfSURBVHjaYmRABcYwBiM2QSA4y4hNEKYDQxAEAAIMAHNGAzhkPOlYAAAAAElFTkSuQmCC) - repeat-x 0 0; - border: 0 none; - color: #ccc; - height: 4px; - margin: 16px 0; - padding: 0; -} -h1 + p, -h2 + p, -h3 + p, -h4 + p, -h5 + p, -h6 + p, -ul li > :first-child, -ol li > :first-child { - margin-top: 0; -} -dl { - padding: 0; -} -dl dt { - font-size: 1em; - font-weight: bold; - font-style: italic; - padding: 0; - margin: 15px 0 5px; -} -dl dt:first-child { - padding: 0; -} -dl dt > :first-child { - margin-top: 0; -} -dl dt > :last-child { - margin-bottom: 0; -} -dl dd { - margin: 0 0 15px; - padding: 0 15px; -} -dl dd > :first-child { - margin-top: 0; -} -dl dd > :last-child { - margin-bottom: 0; -} -blockquote { - border-left: 4px solid #ddd; - padding: 0 15px; - color: #777; -} -blockquote > :first-child { - margin-top: 0; -} -blockquote > :last-child { - margin-bottom: 0; -} -table { - border-collapse: collapse; - border-spacing: 0; - font-size: 100%; - font: inherit; -} -table th { - font-weight: normal; - border: 1px solid #ccc; - padding: 6px 13px; -} -table td { - border: 1px solid #ccc; - padding: 6px 13px; -} -table td > p:first-child { - margin-top: 0; -} -table td > p:last-child { - margin-bottom: 0; -} -table tr { - border-top: 1px solid #ccc; - background-color: #fff; -} -table tr:nth-child(2n) { - background-color: #f8f8f8; -} -img { - max-width: 100%; -} - -/* Code - ========================================================================== */ - -code, -tt { - padding: 0; - padding-top: 0.2em; - padding-bottom: 0.2em; - margin: 0; - font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace; - font-size: 10pt; - background-color: rgba(0, 0, 0, 0.04); - border-radius: 3px; -} -pre > code { - margin: 0; - padding: 0; - white-space: pre; - border: 0; - background: transparent; -} -pre { - padding: 16px; - margin-top: 0; - margin-bottom: 0; - background-color: #f8f8f8; - font-size: 10pt; - line-height: 19px; - overflow: auto; - border-radius: 3px; -} -pre code, -pre tt { - background-color: transparent; - border: 0; -} -code::before, -code::after, -tt::before, -tt::after { - letter-spacing: -0.2em; - content: "\00a0"; -} -pre code::before, -pre code::after, -pre tt::before, -pre tt::after { - content: normal; -} -code > span.kw { - color: #a71d5d; - font-weight: normal; -} /* Keyword */ -code > span.dt { - color: inherit; -} /* DataType */ -code > span.dv { - color: #0086b3; -} /* DecVal */ -code > span.bn { - color: #0086b3; -} /* BaseN */ -code > span.fl { - color: #0086b3; -} /* Float */ -code > span.ch { - color: #183691; -} /* Char */ -code > span.st { - color: #183691; -} /* String */ -code > span.co { - color: #969896; - font-style: normal; -} /* Comment */ -code > span.ot { - color: #a71d5d; -} /* Other */ -code > span.al { - color: #ff0000; -} /* Alert */ -code > span.fu { - color: #795da3; -} /* Function */ -code > span.er { - color: #ff0000; - font-weight: bold; -} /* Error */ -code > span.wa { - color: #969896; - font-weight: bold; - font-style: italic; -} /* Warning */ -code > span.cn { - color: #880000; -} /* Constant */ -code > span.sc { - color: #183691; -} /* SpecialChar */ -code > span.vs { - color: #183691; -} /* VerbatimString */ -code > span.ss { - color: #bb6688; -} /* SpecialString */ -code > span.im { -} /* Import */ -code > span.va { - color: #19177c; -} /* Variable */ -code > span.cf { - color: #a71d5d; - font-weight: normal; -} /* ControlFlow */ -code > span.op { - color: #666666; -} /* Operator */ -code > span.bu { -} /* BuiltIn */ -code > span.ex { -} /* Extension */ -code > span.pp { - color: #bc7a00; -} /* Preprocessor */ -code > span.at { - color: #0086b3; -} /* Attribute */ -code > span.do { - color: #ba2121; - font-style: italic; -} /* Documentation */ -code > span.an { - color: #969896; - font-weight: bold; - font-style: italic; -} /* Annotation */ -code > span.cv { - color: #969896; - font-weight: bold; - font-style: italic; -} /* CommentVar */ -code > span.in { - color: #969896; - font-weight: bold; - font-style: italic; -} /* Information */ - -/* Print - ========================================================================== */ - -@media print { - body { - background: #fff; - } - img, - pre, - blockquote, - table, - figure { - page-break-inside: avoid; - } - body { - background: #fff; - border: 0; - } - code { - background-color: #fff; - color: #333 !important; - padding: 0 0.2em; - border: 1px solid #dedede; - } - pre { - background: #fff; - } - pre code { - background-color: white !important; - overflow: visible; - } -} - -/* Selection - ========================================================================== */ - -@media screen { - ::selection { - background: rgba(157, 193, 200, 0.5); - } - h1::selection { - background-color: rgba(45, 156, 208, 0.3); - } - h2::selection { - background-color: rgba(90, 182, 224, 0.3); - } - h3::selection, - h4::selection, - h5::selection, - h6::selection, - li::selection, - ol::selection { - background-color: rgba(133, 201, 232, 0.3); - } - code::selection { - background-color: rgba(0, 0, 0, 0.7); - color: #eee; - } - code span::selection { - background-color: rgba(0, 0, 0, 0.7) !important; - color: #eee !important; - } - a::selection { - background-color: rgba(255, 230, 102, 0.2); - } - .inverted a::selection { - background-color: rgba(255, 230, 102, 0.6); - } - td::selection, - th::selection, - caption::selection { - background-color: rgba(180, 237, 95, 0.5); - } -} - -/*lists highlighting*/ -/* li p { - background-color: rgb(255,0,0); - } */ - -/* CUSTOM CSS -========================================================================== */ - -.NO > div:first-child, -.EX > div:first-child, -.TAN > div:first-child { - text-wrap: nowrap; -} - -#Table_6\.2-1 + table tbody { - tr { - background-color: #fff !important; - } - - tr:nth-child(4), - tr:nth-child(5), - tr:nth-child(6), - tr:nth-child(7), - tr:nth-child(10), - tr:nth-child(11), - tr:nth-child(12), - tr:nth-child(15), - tr:nth-child(16), - tr:nth-child(17), - tr:nth-child(19), - tr:nth-child(21), - tr:nth-child(24), - tr:nth-child(25), - tr:nth-child(26), - tr:nth-child(29), - tr:nth-child(30), - tr:nth-child(31), - tr:nth-child(33), - tr:nth-child(35), - tr:nth-child(37), - tr:nth-child(40), - tr:nth-child(41), - tr:nth-child(43), - tr:nth-child(46), - tr:nth-child(47), - tr:nth-child(49), - tr:nth-child(50), - tr:nth-child(53), - tr:nth-child(54), - tr:nth-child(58), - tr:nth-child(61), - tr:nth-child(62), - tr:nth-child(63) { - background-color: #f8f8f8 !important; - } -} diff --git a/public/0--1.html b/public/0--1.html new file mode 100644 index 0000000000000000000000000000000000000000..f7ec681fc2337eeb6d8440fa82503dbe0abad30a --- /dev/null +++ b/public/0--1.html @@ -0,0 +1,4748 @@ + + + + + + + temp + + + + + + + + +
+ETSI GS CIM 009 V1.8.14 (2024-10) +
+
+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. +
+
+Group +Specification +
+
+
+Reference +
+
+RGS/CIM-009v181 +
+
+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:
+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 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 2024. +
+
+All rights +reserved.
+ +
+
+ +
+

Intellectual Property Rights 18

+

Foreword 18

+

Modal verbs terminology 18

+

Executive summary 18

+

Introduction 19

+

1 Scope 20

+

2 References 20

+

2.1 Normative references 20

+

2.2 Informative references 21

+

3 Definition of terms, symbols and abbreviations 22

+

3.1 Terms 22

+

3.2 Symbols 25

+

3.3 Abbreviations 25

+

4 Context Information Management Framework 27

+

4.1 Introduction 27

+

4.2 NGSI-LD Information Model 27

+

4.2.1 Introduction 27

+

4.2.2 NGSI-LD Meta Model 27

+

4.2.3 Cross Domain Ontology 29

+

4.2.4 NGSI-LD domain-specific models and instantiation 30

+

4.2.5 UML representation 30

+

4.3 NGSI-LD Architectural Considerations 31

+

4.3.1 Introduction 31

+

4.3.2 Centralized architecture 31

+

4.3.3 Distributed architecture 32

+

4.3.4 Federated architecture 33

+

4.3.5 NGSI-LD API Structure and Implementation Options 34

+

4.3.6 Distributed Operations 38

+

4.3.6.1 Introduction 38

+

4.3.6.2 Additive Registrations 39

+

4.3.6.3 Proxied Registrations 39

+

4.3.6.4 Limiting Cascading Distributed Operations 40

+

4.3.6.5 Extra information to provide when contacting Context Source 40

+

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

+

4.3.6.7 Querying and Retrieving Distributed Entities as Unitary +Operations 41

+

4.3.6.8 Backwards compatibility of Context Source payloads 42

+

4.4 Core and user NGSI-LD @context 43

+

4.5 NGSI-LD Data Representation 44

+

4.5.0 Introduction 44

+

4.5.1 NGSI-LD Entity Representation 45

+

4.5.2 NGSI-LD Property Representations 45

+

4.5.2.1 Introduction 45

+

4.5.2.2 Normalized NGSI-LD Property 46

+

4.5.2.3 Concise NGSI-LD Property 47

+

4.5.3 NGSI-LD Relationship Representations 48

+

4.5.3.1 Introduction 48

+

4.5.3.2 Normalized NGSI-LD Relationship 49

+

4.5.3.3 Concise NGSI-LD Relationship 50

+

4.5.4 Simplified Representation 51

+

4.5.5 Multi-Attribute Support 56

+

4.5.5.1 Introduction 56

+

4.5.5.2 Processing of Conflicting Transient Entities 56

+

4.5.5.3 Processing of Conflicting Attributes 56

+

4.5.6 Temporal Representation of an Entity 57

+

4.5.7 Temporal Representation of a Property 57

+

4.5.8 Temporal Representation of a Relationship 57

+

4.5.9 Simplified temporal representation of an Entity 57

+

4.5.10 Entity Type List Representation 61

+

4.5.11 Detailed Entity Type List Representation 61

+

4.5.12 Entity Type Information Representation 62

+

4.5.13 Attribute List Representation 62

+

4.5.14 Detailed Attribute List Representation 62

+

4.5.15 Attribute Information Representation 62

+

4.5.16 GeoJSON Representation of Entities 63

+

4.5.16.0 Foreword 63

+

4.5.16.1 Top-level "geometry" field selection algorithm 63

+

4.5.16.2 GeoJSON Representation of an individual Entity 63

+

4.5.16.3 GeoJSON Representation of Multiple Entities 64

+

4.5.17 Simplified GeoJSON Representation of Entities 64

+

4.5.17.0 Foreword 64

+

4.5.17.1 Simplified GeoJSON Representation of an individual Entity 64

+

4.5.17.2 Simplified GeoJSON Representation of multiple Entities 65

+

4.5.18 NGSI-LD LanguageProperty Representations 65

+

4.5.18.1 Introduction 65

+

4.5.18.2 Normalized NGSI-LD LanguageProperty 66

+

4.5.18.3 Concise NGSI-LD LanguageProperty 66

+

4.5.19 Aggregated temporal representation of an Entity 67

+

4.5.19.0 Foreword 67

+

4.5.19.1 Supported behaviours for aggregation functions 68

+

4.5.20 NGSI-LD VocabProperty Representations 69

+

4.5.20.1 Introduction 69

+

4.5.20.2 Normalized NGSI-LD VocabProperty 70

+

4.5.20.3 Concise NGSI-LD VocabProperty 70

+

4.5.21 NGSI-LD ListProperty Representations 71

+

4.5.21.1 Introduction 71

+

4.5.21.2 Normalized NGSI-LD ListProperty 71

+

4.5.21.3 Concise NGSI-LD ListProperty 71

+

4.5.22 NGSI-LD ListRelationship Representations 72

+

4.5.22.1 Introduction 72

+

4.5.22.2 Normalized NGSI-LD ListRelationship 72

+

4.5.22.3 Concise NGSI-LD ListRelationship 73

+

4.5.23 NGSI-LD Linked Entity Retrieval 73

+

4.5.23.1 Introduction 73

+

4.5.23.2 Inline Linked Entity Representation 73

+

4.5.23.3 Flattened Linked Entity Representation 74

+

4.5.24 NGSI-LD JsonProperty Representations 74

+

4.5.24.1 Introduction 74

+

4.5.24.2 Normalized NGSI-LD JsonProperty 74

+

4.5.24.3 Concise NGSI-LD JsonProperty 74

+

4.5.25 NGSI-LD EntityMap Representation 75

+

4.6 Data Representation Restrictions 75

+

4.6.1 Supported text encodings 75

+

4.6.2 Supported names 76

+

4.6.3 Supported data types for Values 76

+

4.6.4 Supported Content 77

+

4.6.5 Supported data types for LanguageMaps 78

+

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

+

4.7 Geospatial Properties 78

+

4.7.1 GeoJSON Geometries 78

+

4.7.2 Representation of GeoJSON Geometries in JSON-LD 78

+

4.7.3 Concise NGSI-LD GeoProperty 79

+

4.8 Temporal Properties 79

+

4.9 NGSI-LD Query Language 80

+

4.10 NGSI-LD Geoquery Language 87

+

4.11 NGSI-LD Temporal Query Language 89

+

4.12 NGSI-LD Pagination 90

+

4.13 Counting the Number of Results 91

+

4.14 Supporting Multiple Tenants 91

+

4.15 NGSI-LD Language Filter 91

+

4.16 Supporting Multiple Entity Types 92

+

4.17 NGSI-LD Entity Type Selection Language 92

+

4.18 NGSI-LD Scopes 93

+

4.19 NGSI-LD Scope Query Language 93

+

4.20 NGSI-LD Distributed Operation names 94

+

4.21 NGSI-LD Attribute Projection Language 96

+

4.22 Transient Storage of Entities and Attributes 96

+

5 API Operation Definition 97

+

5.1 Introduction 97

+

5.2 Data Types 97

+

5.2.1 Introduction 97

+

5.2.2 Common members 97

+

5.2.3 @context 98

+

5.2.4 Entity 98

+

5.2.5 Property 99

+

5.2.6 Relationship 101

+

5.2.7 GeoProperty 103

+

5.2.8 EntityInfo 104

+

5.2.9 CSourceRegistration 105

+

5.2.10 RegistrationInfo 108

+

5.2.11 TimeInterval 108

+

5.2.12 Subscription 109

+

5.2.13 GeoQuery 111

+

5.2.14 NotificationParams 111

+

5.2.14.1 NotificationParams data type definition 111

+

5.2.14.2 Output only members 112

+

5.2.15 Endpoint 113

+

5.2.16 BatchOperationResult 114

+

5.2.17 BatchEntityError 114

+

5.2.18 UpdateResult 115

+

5.2.19 NotUpdatedDetails 115

+

5.2.20 EntityTemporal 115

+

5.2.21 TemporalQuery 115

+

5.2.22 KeyValuePair 116

+

5.2.23 Query 116

+

5.2.24 EntityTypeList 119

+

5.2.25 EntityType 119

+

5.2.26 EntityTypeInfo 119

+

5.2.27 AttributeList 120

+

5.2.28 Attribute 120

+

5.2.29 Feature 121

+

5.2.30 FeatureCollection 121

+

5.2.31 FeatureProperties 122

+

5.2.32 LanguageProperty 122

+

5.2.33 EntitySelector 124

+

5.2.34 RegistrationManagementInfo 124

+

5.2.35 VocabProperty 126

+

5.2.36 ListProperty 127

+

5.2.37 ListRelationship 128

+

5.2.38 JsonProperty 131

+

5.2.39 EntityMap 132

+

5.2.40 Context Source Identity 133

+

5.3 Notification data types 133

+

5.3.1 Notification 133

+

5.3.2 CSourceNotification 134

+

5.3.3 TriggerReasonEnumeration 135

+

5.4 NGSI-LD Fragments 135

+

5.5 Common Behaviours 136

+

5.5.1 Introduction 136

+

5.5.2 Error types 136

+

5.5.3 Error response payload body 136

+

5.5.4 General NGSI-LD validation 137

+

5.5.5 Default @context assignment 137

+

5.5.6 Operation execution and generic error handling 137

+

5.5.7 Term to URI expansion or compaction 138

+

5.5.8 Partial Update Patch Behaviour 139

+

5.5.9 Pagination Behaviour 140

+

5.5.10 Multi-Tenant Behaviour 141

+

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

+

5.5.11.0 Foreword 142

+

5.5.11.1 Batch Entity Creation case 142

+

5.5.11.2 Batch Entity Creation or Update (Upsert) case 143

+

5.5.11.3 Batch Entity Update case 143

+

5.5.11.4 Batch Entity Delete case 143

+

5.5.11.5 Batch Entity Merge case 143

+

5.5.12 Merge Patch Behaviour 143

+

5.5.13 Limiting operations to local scope 145

+

5.5.14 Distributed Transactional Behaviour 145

+

5.6 Context Information Provision 145

+

5.6.1 Create Entity 145

+

5.6.1.1 Description 145

+

5.6.1.2 Use case diagram 146

+

5.6.1.3 Input data 146

+

5.6.1.4 Behaviour 146

+

5.6.1.5 Output data 147

+

5.6.2 Update Attributes 147

+

5.6.2.1 Description 147

+

5.6.2.2 Use case diagram 147

+

5.6.2.3 Input data 147

+

5.6.2.4 Behaviour 147

+

5.6.2.5 Output data 148

+

5.6.3 Append Attributes 149

+

5.6.3.1 Description 149

+

5.6.3.2 Use case diagram 149

+

5.6.3.3 Input data 149

+

5.6.3.4 Behaviour 149

+

5.6.3.5 Output data 150

+

5.6.4 Partial Attribute update 150

+

5.6.4.1 Description 150

+

5.6.4.2 Use case diagram 151

+

5.6.4.3 Input data 151

+

5.6.4.4 Behaviour 151

+

5.6.4.5 Output data 152

+

5.6.5 Delete Attribute 152

+

5.6.5.1 Description 152

+

5.6.5.2 Use case diagram 152

+

5.6.5.3 Input data 153

+

5.6.5.4 Behaviour 153

+

5.6.5.5 Output data 154

+

5.6.6 Delete Entity 154

+

5.6.6.1 Description 154

+

5.6.6.2 Use case diagram 154

+

5.6.6.3 Input data 154

+

5.6.6.4 Behaviour 154

+

5.6.6.5 Output data 155

+

5.6.7 Batch Entity Creation 155

+

5.6.7.1 Description 155

+

5.6.7.2 Use case diagram 155

+

5.6.7.3 Input data 155

+

5.6.7.4 Behaviour 156

+

5.6.7.5 Output data 157

+

5.6.8 Batch Entity Creation or Update (Upsert) 157

+

5.6.8.1 Description 157

+

5.6.8.2 Use case diagram 157

+

5.6.8.3 Input data 157

+

5.6.8.4 Behaviour 157

+

5.6.8.5 Output data 159

+

5.6.9 Batch Entity Update 159

+

5.6.9.1 Description 159

+

5.6.9.2 Use case diagram 159

+

5.6.9.3 Input data 160

+

5.6.9.4 Behaviour 160

+

5.6.9.5 Output data 161

+

5.6.10 Batch Entity Delete 161

+

5.6.10.1 Description 161

+

5.6.10.2 Use case diagram 161

+

5.6.10.3 Input data 162

+

5.6.10.4 Behaviour 162

+

5.6.10.5 Output data 163

+

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

+

5.6.11.1 Description 163

+

5.6.11.2 Use case diagram 163

+

5.6.11.3 Input data 164

+

5.6.11.4 Behaviour 164

+

5.6.11.5 Output data 165

+

5.6.12 Add Attributes to Temporal Evolution of an Entity 165

+

5.6.12.1 Description 165

+

5.6.12.2 Use case diagram 165

+

5.6.12.3 Input data 165

+

5.6.12.4 Behaviour 165

+

5.6.12.5 Output data 166

+

5.6.13 Delete Attribute from Temporal Evolution of an Entity 166

+

5.6.13.1 Description 166

+

5.6.13.2 Use case diagram 166

+

5.6.13.3 Input data 167

+

5.6.13.4 Behaviour 167

+

5.6.13.5 Output data 168

+

5.6.14 Modify Attribute instance in Temporal Evolution of an Entity 168

+

5.6.14.1 Description 168

+

5.6.14.2 Use case diagram 168

+

5.6.14.3 Input data 169

+

5.6.14.4 Behaviour 169

+

5.6.14.5 Output data 169

+

5.6.15 Delete Attribute instance from Temporal Evolution of an +Entity 170

+

5.6.15.1 Description 170

+

5.6.15.2 Use case diagram 170

+

5.6.15.3 Input data 170

+

5.6.15.4 Behaviour 170

+

5.6.15.5 Output data 171

+

5.6.16 Delete Temporal Evolution of an Entity 171

+

5.6.16.1 Description 171

+

5.6.16.2 Use case diagram 171

+

5.6.16.3 Input data 172

+

5.6.16.4 Behaviour 172

+

5.6.16.5 Output data 172

+

5.6.17 Merge Entity 173

+

5.6.17.1 Description 173

+

5.6.17.2 Use case diagram 173

+

5.6.17.3 Input data 173

+

5.6.17.4 Behaviour 173

+

5.6.17.5 Output data 175

+

5.6.18 Replace Entity 175

+

5.6.18.1 Description 175

+

5.6.18.2 Use case diagram 175

+

5.6.18.3 Input data 176

+

5.6.18.4 Behaviour 176

+

5.6.18.5 Output data 177

+

5.6.19 Replace Attribute 177

+

5.6.19.1 Description 177

+

5.6.19.2 Use case diagram 177

+

5.6.19.3 Input data 177

+

5.6.19.4 Behaviour 177

+

5.6.19.5 Output data 178

+

5.6.20 Batch Entity Merge 178

+

5.6.20.1 Description 178

+

5.6.20.2 Use case diagram 178

+

5.6.20.3 Input data 179

+

5.6.20.4 Behaviour 179

+

5.6.20.5 Output data 180

+

5.6.21 Purge Entities 180

+

5.6.21.1 Description 180

+

5.6.21.2 Use case diagram 180

+

5.6.21.3 Input data 181

+

5.6.21.4 Behaviour 181

+

5.6.21.5 Output data 182

+

5.7 Context Information Consumption 182

+

5.7.1 Retrieve Entity 182

+

5.7.1.1 Description 182

+

5.7.1.2 Use case diagram 182

+

5.7.1.3 Input data 183

+

5.7.1.4 Behaviour 184

+

5.7.1.5 Output data 185

+

5.7.2 Query Entities 186

+

5.7.2.1 Description 186

+

5.7.2.2 Use case diagram 186

+

5.7.2.3 Input data 186

+

5.7.2.4 Behaviour 187

+

5.7.2.5 Output data 190

+

5.7.3 Retrieve Temporal Evolution of an Entity 190

+

5.7.3.1 Description 190

+

5.7.3.2 Use case diagram 190

+

5.7.3.3 Input data 191

+

5.7.3.4 Behaviour 191

+

5.7.3.5 Output data 192

+

5.7.4 Query Temporal Evolution of Entities 193

+

5.7.4.1 Description 193

+

5.7.4.2 Use case diagram 193

+

5.7.4.3 Input data 193

+

5.7.4.4 Behaviour 194

+

5.7.4.5 Output Data 197

+

5.7.5 Retrieve Available Entity Types 197

+

5.7.5.1 Description 197

+

5.7.5.2 Use case diagram 197

+

5.7.5.3 Input data 197

+

5.7.5.4 Behaviour 197

+

5.7.5.5 Output data 198

+

5.7.6 Retrieve Details of Available Entity Types 198

+

5.7.6.1 Description 198

+

5.7.6.2 Use case diagram 198

+

5.7.6.3 Input data 198

+

5.7.6.4 Behaviour 198

+

5.7.6.5 Output data 198

+

5.7.7 Retrieve Available Entity Type Information 199

+

5.7.7.1 Description 199

+

5.7.7.2 Use case diagram 199

+

5.7.7.3 Input data 199

+

5.7.7.4 Behaviour 199

+

5.7.7.5 Output data 199

+

5.7.8 Retrieve Available Attributes 199

+

5.7.8.1 Description 199

+

5.7.8.2 Use case diagram 200

+

5.7.8.3 Input data 200

+

5.7.8.4 Behaviour 200

+

5.7.8.5 Output data 200

+

5.7.9 Retrieve Details of Available Attributes 200

+

5.7.9.1 Description 200

+

5.7.9.2 Use case diagram 200

+

5.7.9.3 Input data 201

+

5.7.9.4 Behaviour 201

+

5.7.9.5 Output data 201

+

5.7.10 Retrieve Available Attribute Information 201

+

5.7.10.1 Description 201

+

5.7.10.2 Use case diagram 201

+

5.7.10.3 Input data 202

+

5.7.10.4 Behaviour 202

+

5.7.10.5 Output data 202

+

5.7.11 Architecture-related aspects of retrieval of Entity Types and +Attributes 202

+

5.8 Context Information Subscription 203

+

5.8.1 Create Subscription 203

+

5.8.1.1 Description 203

+

5.8.1.2 Use case diagram 203

+

5.8.1.3 Input data 203

+

5.8.1.4 Behaviour 203

+

5.8.1.5 Output data 205

+

5.8.2 Update Subscription 205

+

5.8.2.1 Description 205

+

5.8.2.2 Use case diagram 205

+

5.8.2.3 Input data 205

+

5.8.2.4 Behaviour 206

+

5.8.2.5 Output data 206

+

5.8.3 Retrieve Subscription 206

+

5.8.3.1 Description 206

+

5.8.3.2 Use case diagram 206

+

5.8.3.3 Input data 207

+

5.8.3.4 Behaviour 207

+

5.8.3.5 Output data 207

+

5.8.4 Query Subscriptions 207

+

5.8.4.1 Description 207

+

5.8.4.2 Use case diagram 207

+

5.8.4.3 Input data 208

+

5.8.4.4 Behaviour 208

+

5.8.4.5 Output data 208

+

5.8.5 Delete Subscription 208

+

5.8.5.1 Description 208

+

5.8.5.2 Use case diagram 208

+

5.8.5.3 Input data 209

+

5.8.5.4 Behaviour 209

+

5.8.5.5 Output data 209

+

5.8.6 Notification behaviour 209

+

5.9 Context Source Registration 211

+

5.9.1 Introduction 211

+

5.9.2 Register Context Source 211

+

5.9.2.1 Description 211

+

5.9.2.2 Use case diagram 212

+

5.9.2.3 Input data 212

+

5.9.2.4 Behaviour 212

+

5.9.2.5 Output data 213

+

5.9.3 Update Context Source Registration 213

+

5.9.3.1 Description 213

+

5.9.3.2 Use case diagram 213

+

5.9.3.3 Input data 213

+

5.9.3.4 Behaviour 214

+

5.9.3.5 Output data 214

+

5.9.4 Delete Context Source Registration 214

+

5.9.4.1 Description 214

+

5.9.4.2 Use case diagram 214

+

5.9.4.3 Input data 215

+

5.9.4.4 Behaviour 215

+

5.9.4.5 Output data 215

+

5.10 Context Source Discovery 215

+

5.10.1 Retrieve Context Source Registration 215

+

5.10.1.1 Description 215

+

5.10.1.2 Use case diagram 215

+

5.10.1.3 Input data 216

+

5.10.1.4 Behaviour 216

+

5.10.1.5 Output data 216

+

5.10.2 Query Context Source Registrations 216

+

5.10.2.1 Description 216

+

5.10.2.2 Use case diagram 217

+

5.10.2.3 Input data 217

+

5.10.2.4 Behaviour 218

+

5.10.2.5 Output data 219

+

5.11 Context Source Registration Subscription 219

+

5.11.1 Introduction 219

+

5.11.2 Create Context Source Registration Subscription 219

+

5.11.2.1 Description 219

+

5.11.2.2 Use case diagram 219

+

5.11.2.3 Input data 219

+

5.11.2.4 Behaviour 220

+

5.11.2.5 Output data 221

+

5.11.3 Update Context Source Registration Subscription 221

+

5.11.3.1 Description 221

+

5.11.3.2 Use case diagram 221

+

5.11.3.3 Input data 221

+

5.11.3.4 Behaviour 221

+

5.11.3.5 Output data 221

+

5.11.4 Retrieve Context Source Registration Subscription 222

+

5.11.4.1 Description 222

+

5.11.4.2 Use case diagram 222

+

5.11.4.3 Input data 222

+

5.11.4.4 Behaviour 222

+

5.11.4.5 Output data 222

+

5.11.5 Query Context Source Registration Subscriptions 222

+

5.11.5.1 Description 222

+

5.11.5.2 Use case diagram 223

+

5.11.5.3 Input data 223

+

5.11.5.4 Behaviour 223

+

5.11.5.5 Output data 223

+

5.11.6 Delete Context Source Registration Subscription 223

+

5.11.6.1 Description 223

+

5.11.6.2 Use case diagram 223

+

5.11.6.3 Input data 224

+

5.11.6.4 Behaviour 224

+

5.11.6.5 Output data 224

+

5.11.7 Notification behaviour 224

+

5.12 Matching Context Source +Registrations 225

+

5.13 Storing, Managing and Serving @contexts 226

+

5.13.1 Introduction 226

+

5.13.2 Add @context 227

+

5.13.2.1 Description 227

+

5.13.2.2 Use case diagram 227

+

5.13.2.3 Input data 227

+

5.13.2.4 Behaviour 228

+

5.13.2.5 Output data 228

+

5.13.3 List @contexts 228

+

5.13.3.1 Description 228

+

5.13.3.2 Use case diagram 228

+

5.13.3.3 Input data 228

+

5.13.3.4 Behaviour 229

+

5.13.3.5 Output data 229

+

5.13.4 Serve @context 229

+

5.13.4.1 Description 229

+

5.13.4.2 Use case diagram 229

+

5.13.4.3 Input data 230

+

5.13.4.4 Behaviour 230

+

5.13.4.5 Output data 230

+

5.13.5 Delete and Reload @context 230

+

5.13.5.1 Description 230

+

5.13.5.2 Use case diagram 230

+

5.13.5.3 Input data 231

+

5.13.5.4 Behaviour 231

+

5.13.5.5 Output data 231

+

5.14 Context Source Entity Mapping 231

+

5.14.1 Retrieve EntityMap 231

+

5.14.1.1 Description 231

+

5.14.1.2 Use case diagram 231

+

5.14.1.3 Input data 232

+

5.14.1.4 Behaviour 232

+

5.14.1.5 Output data 232

+

5.14.2 Update EntityMap 232

+

5.14.2.1 Description 232

+

5.14.2.2 Use case diagram 232

+

5.14.2.3 Input data 233

+

5.14.2.4 Behaviour 233

+

5.14.2.5 Output data 233

+

5.14.3 Delete EntityMap 233

+

5.14.3.1 Description 233

+

5.14.3.2 Use case diagram 233

+

5.14.3.3 Input data 234

+

5.14.3.4 Behaviour 234

+

5.14.3.5 Output data 234

+

5.14.4 Create EntityMap for Query Entities 234

+

5.14.4.1 Description 234

+

5.14.4.2 Use case diagram 234

+

5.14.4.3 Input data 235

+

5.14.4.4 Behaviour 236

+

5.14.4.5 Output data 237

+

5.14.5 Create EntityMap for Query Temporal Evolution of Entities 238

+

5.14.5.1 Description 238

+

5.14.5.2 Use case diagram 238

+

5.14.5.3 Input data 238

+

5.14.5.4 Behaviour 239

+

5.7.4.5 Output Data 241

+

5.15 Context Source Identity Information 241

+

5.15.1 Retrieve Context Source Identity Information 241

+

5.15.1.1 Description 241

+

5.15.1.2 Use case diagram 241

+

5.15.1.3 Input data 242

+

5.15.1.4 Behaviour 242

+

5.14.1.5 Output data 242

+

6 API HTTP Binding 242

+

6.1 Introduction 242

+

6.2 Global Definitions and Resource Structure 242

+

6.3 Common Behaviours 246

+

6.3.1 Introduction 246

+

6.3.2 Error Types 247

+

6.3.3 Reporting errors 247

+

6.3.4 HTTP request preconditions 247

+

6.3.5 JSON-LD @context resolution 248

+

6.3.6 HTTP response common requirements 249

+

6.3.7 Representation of Entities 249

+

6.3.8 Notification behaviour 250

+

6.3.9 Csource Notification behaviour 251

+

6.3.10 Pagination behaviour 251

+

6.3.11 Including system Attributes 253

+

6.3.12 Simplified or aggregated temporal representation of Entities 253

+

6.3.13 Counting number of results 254

+

6.3.14 Tenant specification 254

+

6.3.15 GeoJSON representation of spatially bound entities 254

+

6.3.16 Expiration time for cached @contexts 254

+

6.3.17 Distributed Operations Caching and Timeout Behaviour 255

+

6.3.18 Limiting Distributed Operations 255

+

6.3.19 Extra information to provide when contacting Context Source 256

+

6.3.20 Invalid parameters 256

+

6.3.21 Optional profile information regarding versioning and datatype +conformance 256

+

6.4 Resource: entities/ 257

+

6.4.1 Description 257

+

6.4.2 Resource definition 257

+

6.4.3 Resource methods 257

+

6.4.3.1 POST 257

+

6.4.3.2 GET 258

+

6.4.3.3 DELETE 262

+

6.5 Resource: entities/{entityId} 264

+

6.5.1 Description 264

+

6.5.2 Resource definition 264

+

6.5.3 Resource methods 265

+

6.5.3.1 GET 265

+

6.5.3.2 DELETE 267

+

6.5.3.3 PUT 268

+

6.5.3.4 PATCH 270

+

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

+

6.6.1 Description 271

+

6.6.2 Resource definition 271

+

6.6.3 Resource methods 272

+

6.6.3.1 POST 272

+

6.6.3.2 PATCH 273

+

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

+

6.7.1 Description 274

+

6.7.2 Resource definition 274

+

6.7.3 Resource methods 275

+

6.7.3.1 PATCH 275

+

6.7.3.2 DELETE 276

+

6.7.3.3 PUT 277

+

6.8 Resource: csourceRegistrations/ 279

+

6.8.1 Description 279

+

6.8.2 Resource definition 279

+

6.8.3 Resource methods 279

+

6.8.3.1 POST 279

+

6.8.3.2 GET 280

+

6.9 Resource: csourceRegistrations/{registrationId} 282

+

6.9.1 Description 282

+

6.9.2 Resource definition 282

+

6.9.3 Resource methods 282

+

6.9.3.1 GET 282

+

6.9.3.2 PATCH 283

+

6.9.3.3 DELETE 284

+

6.10 Resource: subscriptions/ 285

+

6.10.1 Description 285

+

6.10.2 Resource definition 285

+

6.10.3 Resource methods 285

+

6.10.3.1 POST 285

+

6.10.3.2 GET 286

+

6.11 Resource: subscriptions/{subscriptionId} 286

+

6.11.1 Description 286

+

6.11.2 Resource definition 286

+

6.11.3 Resource methods 287

+

6.11.3.1 GET 287

+

6.11.3.2 PATCH 287

+

6.11.3.3 DELETE 288

+

6.12 Resource: csourceSubscriptions/ 289

+

6.12.1 Description 289

+

6.12.2 Resource definition 289

+

6.12.3 Resource methods 289

+

6.12.3.1 POST 289

+

6.12.3.2 GET 290

+

6.13 Resource: csourceSubscriptions/{subscriptionId} 291

+

6.13.1 Description 291

+

6.13.2 Resource definition 291

+

6.13.3 Resource methods 291

+

6.13.3.1 GET 291

+

6.13.3.2 PATCH 292

+

6.13.3.3 DELETE 293

+

6.14 Resource: entityOperations/create 293

+

6.14.1 Description 293

+

6.14.2 Resource definition 294

+

6.14.3 Resource methods 294

+

6.14.3.1 POST 294

+

6.15 Resource: entityOperations/upsert 295

+

6.15.1 Description 295

+

6.15.2 Resource definition 295

+

6.15.3 Resource methods 296

+

6.15.3.1 POST 296

+

6.16 Resource: entityOperations/update 297

+

6.16.1 Description 297

+

6.16.2 Resource definition 298

+

6.16.3 Resource methods 298

+

6.16.3.1 POST 298

+

6.17 Resource: entityOperations/delete 299

+

6.17.1 Description 299

+

6.17.2 Resource definition 299

+

6.17.3 Resource methods 300

+

6.17.3.1 POST 300

+

6.18 Resource: temporal/entities/ 301

+

6.18.1 Description 301

+

6.18.2 Resource definition 301

+

6.18.3 Resource methods 301

+

6.18.3.1 POST 301

+

6.18.3.2 GET 302

+

6.19 Resource: temporal/entities/{entityId} 305

+

6.19.1 Description 305

+

6.19.2 Resource definition 305

+

6.19.3 Resource methods 305

+

6.19.3.1 GET 305

+

6.19.3.2 DELETE 307

+

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

+

6.20.1 Description 307

+

6.20.2 Resource definition 308

+

6.20.3 Resource methods 308

+

6.20.3.1 POST 308

+

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

+

6.21.1 Description 309

+

6.21.2 Resource definition 309

+

6.21.3 Resource methods 309

+

6.21.3.1 DELETE 309

+

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

+

6.22.1 Description 310

+

6.22.2 Resource definition 310

+

6.22.3 Resource methods 310

+

6.22.3.1 PATCH 310

+

6.22.3.2 DELETE 311

+

6.23 Resource: entityOperations/query 312

+

6.23.1 Description 312

+

6.23.2 Resource definition 312

+

6.23.3 Resource methods 312

+

6.23.3.1 POST 312

+

6.24 Resource: temporal/entityOperations/query 314

+

6.24.1 Description 314

+

6.24.2 Resource definition 314

+

6.24.3 Resource methods 314

+

6.24.3.1 POST 314

+

6.25 Resource: types/ 315

+

6.25.1 Description 315

+

6.25.2 Resource definition 315

+

6.25.3 Resource methods 315

+

6.25.3.1 GET 315

+

6.26 Resource: types/{type} 316

+

6.26.1 Description 316

+

6.26.2 Resource definition 316

+

6.26.3 Resource methods 316

+

6.26.3.1 GET 316

+

6.27 Resource: attributes/ 317

+

6.27.1 Description 317

+

6.27.2 Resource definition 317

+

6.27.3 Resource methods 317

+

6.27.3.1 GET 317

+

6.28 Resource: attributes/{attrId} 318

+

6.28.1 Description 318

+

6.28.2 Resource definition 319

+

6.28.3 Resource methods 319

+

6.28.3.1 GET 319

+

6.29 Resource: jsonldContexts/ 320

+

6.29.1 Description 320

+

6.29.2 Resource definition 320

+

6.29.3 Resource methods 320

+

6.29.3.1 POST 320

+

6.29.3.2 GET 320

+

6.30 Resource: jsonldContexts/{contextId} 321

+

6.30.1 Description 321

+

6.30.2 Resource definition 322

+

6.30.3 Resource methods 322

+

6.30.3.1 GET 322

+

6.30.3.2 DELETE 323

+

6.31 Resource: entityOperations/merge 324

+

6.31.1 Description 324

+

6.31.2 Resource definition 324

+

6.31.3 Resource methods 324

+

6.31.3.1 POST 324

+

6.32 Resource: entityMaps/{entityMapId} 325

+

6.32.1 Description 325

+

6.32.2 Resource definition 325

+

6.32.3 Resource methods 326

+

6.32.3.1 GET 326

+

6.32.3.2 PATCH 326

+

6.32.3.3 DELETE 327

+

6.33 Resource: info/sourceIdentity 327

+

6.33.1 Description 327

+

6.33.2 Resource definition 328

+

6.33.3 Resource methods 328

+

6.33.3.1 GET 328

+

6.34 Resource: entityMaps 328

+

6.34.1 Description 328

+

6.34.2 Resource definition 329

+

6.34.3 Resource methods 329

+

6.34.3.2 POST 330

+

6.35 Resource: temporal/entityMaps 331

+

6.35.1 Description 331

+

6.35.2 Resource definition 331

+

6.35.3 Resource methods 331

+

6.35.3.1 GET 331

+

6.35.3.2 POST 332

+

7 API MQTT Notification Binding 333

+

7.1 Introduction 333

+

7.2 Notification behaviour 333

+

Annex +A (normative): NGSI-LD identifier considerations 335

+

A.1 Introduction 335

+

A.2 Entity identifiers 335

+

A.3 NGSI-LD namespace 335

+

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

+

Annex +C (informative): Examples of using the API 342

+

C.1 Introduction 342

+

C.2 Entity Representation 342

+

C.2.1 Property Graph 342

+

C.2.2 Vehicle Entity 343

+

C.2.3 Parking Entity 356

+

C.2.4 @context 362

+

C.3 Context Source Registration 362

+

C.4 Context Subscription 363

+

C.5 HTTP REST API Examples 364

+

C.5.1 Introduction 364

+

C.5.2 Create Entity of Type Vehicle 364

+

C.5.2.1 HTTP Request 364

+

C.5.2.2 HTTP Response 364

+

C.5.3 Query Entities 364

+

C.5.3.1 Introduction 364

+

C.5.3.2 HTTP Request 364

+

C.5.3.3 HTTP Response 365

+

C.5.4 Query Entities (Pagination) 365

+

C.5.4.1 Introduction 365

+

C.5.4.2 HTTP Request 365

+

C.5.4.3 HTTP Response 365

+

C.5.5 Temporal Query 366

+

C.5.5.1 Introduction 366

+

C.5.5.2 HTTP Request #1 366

+

C.5.5.3 HTTP Response #1 366

+

C.5.5.3 HTTP Request #2 366

+

C.5.5.4 HTTP Response #2 367

+

C.5.6 Temporal Query (Simplified Representation) 367

+

C.5.6.1 Introduction 367

+

C.5.6.2 HTTP Request 367

+

C.5.6.3 HTTP Response 367

+

C.5.7 Retrieve Available Entity Types 368

+

C.5.7.1 Introduction 368

+

C.5.7.2 HTTP Request 368

+

C.5.7.3 HTTP Response 368

+

C.5.8 Retrieve Details of Available Entity Types 369

+

C.5.8.1 Introduction 369

+

C.5.8.2 HTTP Request 369

+

C.5.8.3 HTTP Response 369

+

C.5.9 Retrieve Available Entity Type Information 370

+

C.5.9.1 Introduction 370

+

C.5.9.2 HTTP Request 370

+

C.5.9.3 HTTP Response 370

+

C.5.10 Retrieve Available Attributes 371

+

C.5.10.1 Introduction 371

+

C.5.10.2 HTTP Request 371

+

C.5.10.3 HTTP Response 371

+

C.5.11 Retrieve Details of Available Attributes 371

+

C.5.11.1 Introduction 371

+

C.5.11.2 HTTP Request 371

+

C.5.11.3 HTTP Response 372

+

C.5.12 Retrieve Available Attribute Information 372

+

C.5.12.1 Introduction 372

+

C.5.12.2 HTTP Request 372

+

C.5.12.3 HTTP Response 373

+

C.5.13 Query Entities (Natural Language Filtering) 373

+

C.5.13.1 Introduction 373

+

C.5.13.2 HTTP Request 373

+

C.5.13.3 HTTP Response 373

+

C.5.14 Temporal Query (Aggregated Representation) 374

+

C.5.14.1 Introduction 374

+

C.5.14.2 HTTP Request 374

+

C.5.14.3 HTTP Response 374

+

C.5.15 Scope Queries 375

+

C.5.15.1 Introduction 375

+

C.5.15.2 HTTP Request 375

+

C.5.15.3 HTTP Response 375

+

C.5.16 Temporal Scope Queries 376

+

C.5.16.1 Introduction 376

+

C.5.16.2 HTTP Request 376

+

C.5.16.3 HTTP Response 376

+

C.6 Date Representation 378

+

C.7 @context utilization clarifications 379

+

C.8 Link header utilization clarifications 380

+

C.9 @context processing clarifications 382

+

C.10 ValueType datatype utilization clarifications 383

+

Annex +D (informative): Transformation Algorithms 385

+

D.1 Introduction 385

+

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

+

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

+

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

+

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

+

Annex +F (informative): Conventions and syntax guidelines 389

+

Annex +G (informative): Localization and Internationalization Support 390

+

G.0 Foreword 390

+

G.1 Introduction 390

+

G.1.0 Foreword 390

+

G.1.1 Associating an Entity with a Natural Language 390

+

G.1.2 Associating a Property with a Natural Language 390

+

G.1.3 Associating as equivalent entity 391

+

G.2 Natural Language Collation Support 391

+

G.2.0 Foreword 391

+

G.2.1 Maintain collations as metadata 392

+

G.2.2 Route language sensitive queries via a proxy 392

+

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

+

G.3.0 Foreword 392

+

G.3.1 Localizing Dates 392

+

Annex +H (informative): Suggested actuation workflows 394

+

H.1 Actuators and feedback to the consumer 394

+

H.2 Architecture for actuation 394

+

H.3 Structure of Commands and additional Properties 395

+

H.3.0 Introduction 395

+

H.3.1 Property for listing available commands 396

+

H.3.2 Properties for command endpoints 396

+

H.4 Communication model 398

+

H.4.1 Possible communication models 398

+

H.4.2 Subscription/notification model 398

+

H.4.3 Forwarding model 399

+

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

+

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

+

Annex +I (informative): Change history 404

+

History 407

+ + diff --git a/public/1-contents.html b/public/1-contents.html new file mode 100644 index 0000000000000000000000000000000000000000..29fc219bdbe9169b9d9851feb0f88631d62970bf --- /dev/null +++ b/public/1-contents.html @@ -0,0 +1,3930 @@ + + + + + + + Contents + + + + + + + +
+

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 41

+

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 47

+

4.5.10 +Entity Type List Representation 51

+

4.5.11 +Detailed Entity Type List Representation 51

+

4.5.12 +Entity Type Information Representation 51

+

4.5.13 +Attribute List Representation 51

+

4.5.14 +Detailed Attribute List Representation 52

+

4.5.15 +Attribute Information Representation 52

+

4.5.16 +GeoJSON Representation of Entities 52

+

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 56

+

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 63

+

4.5.25 +NGSI-LD EntityMap Representation 64

+

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 65

+

4.6.4 +Supported Content 66

+

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 67

+

4.7.1 +GeoJSON Geometries 67

+

4.7.2 +Representation of GeoJSON Geometries in JSON-LD 68

+

4.7.3 +Concise NGSI-LD GeoProperty 68

+

4.8 +Temporal Properties 68

+

4.9 +NGSI-LD Query Language 69

+

4.10 +NGSI-LD Geoquery Language 77

+

4.11 +NGSI-LD Temporal Query Language 78

+

4.12 +NGSI-LD Pagination 79

+

4.13 +Counting the Number of Results 80

+

4.14 +Supporting Multiple Tenants 80

+

4.15 +NGSI-LD Language Filter 80

+

4.16 +Supporting Multiple Entity Types 81

+

4.17 +NGSI-LD Entity Type Selection Language 81

+

4.18 +NGSI-LD Scopes 82

+

4.19 +NGSI-LD Scope Query Language 82

+

4.20 +NGSI-LD Distributed Operation names 83

+

4.21 +NGSI-LD Attribute Projection Language 85

+

5 +API Operation Definition 85

+

5.1 +Introduction 85

+

5.2 Data +Types 85

+

5.2.1 +Introduction 85

+

5.2.2 +Common members 86

+

5.2.3 +@context 86

+

5.2.4 Entity +86

+

5.2.5 +Property 87

+

5.2.6 +Relationship 89

+

5.2.7 +GeoProperty 90

+

5.2.8 +EntityInfo 91

+

5.2.9 +CSourceRegistration 92

+

5.2.10 +RegistrationInfo 95

+

5.2.11 +TimeInterval 95

+

5.2.12 +Subscription 96

+

5.2.13 +GeoQuery 98

+

5.2.14 +NotificationParams 98

+

5.2.15 +Endpoint 100

+

5.2.16 +BatchOperationResult 101

+

5.2.17 +BatchEntityError 101

+

5.2.18 +UpdateResult 102

+

5.2.19 +NotUpdatedDetails 102

+

5.2.20 +EntityTemporal 102

+

5.2.21 +TemporalQuery 102

+

5.2.22 +KeyValuePair 103

+

5.2.23 Query +103

+

5.2.24 +EntityTypeList 105

+

5.2.25 +EntityType 105

+

5.2.26 +EntityTypeInfo 105

+

5.2.27 +AttributeList 105

+

5.2.28 +Attribute 106

+

5.2.29 +Feature 106

+

5.2.30 +FeatureCollection 107

+

5.2.31 +FeatureProperties 107

+

5.2.32 +LanguageProperty 107

+

5.2.33 +EntitySelector 109

+

5.2.34 +RegistrationManagementInfo 109

+

5.2.35 +VocabProperty 111

+

5.2.36 +ListProperty 113

+

5.2.37 +ListRelationship 115

+

5.2.38 +JsonProperty 117

+

5.2.39 +EntityMap 118

+

5.2.40 +Context Source Identity 120

+

5.3 +Notification data types 120

+

5.3.1 +Notification 120

+

5.3.2 +CSourceNotification 121

+

5.3.3 +TriggerReasonEnumeration 122

+

5.4 +NGSI-LD Fragments 122

+

5.5 +Common Behaviours 123

+

5.5.1 +Introduction 123

+

5.5.2 +Error types 123

+

5.5.3 +Error response payload body 123

+

5.5.4 +General NGSI-LD validation 124

+

5.5.5 +Default @context assignment 124

+

5.5.6 +Operation execution 124

+

5.5.7 +Term to URI expansion or compaction 124

+

5.5.8 +Partial Update Patch Behaviour 125

+

5.5.9 +Pagination Behaviour 127

+

5.5.10 +Multi-Tenant Behaviour 128

+

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

+

5.5.12 +Merge Patch Behaviour 129

+

5.5.13 +Limiting operations to local scope 131

+

5.5.14 +Distributed Transactional Behaviour 131

+

5.6 +Context Information Provision 132

+

5.6.1 +Create Entity 132

+

5.6.2 +Update Attributes 133

+

5.6.3 +Append Attributes 135

+

5.6.4 +Partial Attribute update 137

+

5.6.5 +Delete Attribute 138

+

5.6.6 +Delete Entity 140

+

5.6.7 +Batch Entity Creation 141

+

5.6.8 +Batch Entity Creation or Update (Upsert) 143

+

5.6.9 +Batch Entity Update 146

+

5.6.10 +Batch Entity Delete 148

+

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

+

5.6.12 +Add Attributes to Temporal Evolution of an Entity +151

+

5.6.13 +Delete Attribute from Temporal Evolution of an Entity +152

+

5.6.14 +Modify Attribute instance in Temporal Evolution of an Entity +154

+

5.6.15 +Delete Attribute instance from Temporal Evolution of an Entity +156

+

5.6.16 +Delete Temporal Evolution of an Entity 157

+

5.6.17 +Merge Entity 159

+

5.6.18 +Replace Entity 161

+

5.6.19 +Replace Attribute 162

+

5.6.20 +Batch Entity Merge 164

+

5.7 +Context Information Consumption 166

+

5.7.1 +Retrieve Entity 166

+

5.7.2 +Query Entities 169

+

5.7.3 +Retrieve Temporal Evolution of an Entity 173

+

5.7.4 +Query Temporal Evolution of Entities 175

+

5.7.5 +Retrieve Available Entity Types 178

+

5.7.6 +Retrieve Details of Available Entity Types 179

+

5.7.7 +Retrieve Available Entity Type Information 180

+

5.7.8 +Retrieve Available Attributes 180

+

5.7.9 +Retrieve Details of Available Attributes 181

+

5.7.10 +Retrieve Available Attribute Information 182

+

5.7.11 +Architecture-related aspects of retrieval of Entity Types and Attributes +183

+

5.8 +Context Information Subscription 184

+

5.8.1 +Create Subscription 184

+

5.8.2 +Update Subscription 186

+

5.8.3 +Retrieve Subscription 187

+

5.8.4 +Query Subscriptions 188

+

5.8.5 +Delete Subscription 189

+

5.8.6 +Notification behaviour 190

+

5.9 +Context Source Registration 192

+

5.9.1 +Introduction 192

+

5.9.2 +Register Context Source 192

+

5.9.3 +Update Context Source Registration 194

+

5.9.4 +Delete Context Source Registration 195

+

5.10 +Context Source Discovery 196

+

5.10.1 +Retrieve Context Source Registration 196

+

5.10.2 +Query Context Source Registrations 197

+

5.11 +Context Source Registration Subscription 200

+

5.11.1 +Introduction 200

+

5.11.2 +Create Context Source Registration Subscription 200

+

5.11.3 +Update Context Source Registration Subscription 202

+

5.11.4 +Retrieve Context Source Registration Subscription +203

+

5.11.5 +Query Context Source Registration Subscriptions 203

+

5.11.6 +Delete Context Source Registration Subscription 204

+

5.11.7 +Notification behaviour 205

+

5.12 +Matching Context Source Registrations 206

+

5.13 +Storing, Managing and Serving @contexts 207

+

5.13.1 +Introduction 207

+

5.13.2 +Add @context 208

+

5.13.3 +List @contexts 209

+

5.13.4 +Serve @context 210

+

5.13.5 +Delete and Reload @context 211

+

5.14 +Context Source Entity Mapping 212

+

5.14.1 +Retrieve EntityMap 212

+

5.14.2 +Update EntityMap 213

+

5.14.3 +Delete EntityMap 214

+

5.15 +Context Source Identity Information 215

+

5.15.1 +Retrieve Context Source Identity Information 215

+

6 API HTTP +Binding 216

+

6.1 +Introduction 216

+

6.2 +Global Definitions and Resource Structure 216

+

6.3 +Common Behaviours 220

+

6.3.1 +Introduction 220

+

6.3.2 Error +Types 220

+

6.3.3 +Reporting errors 221

+

6.3.4 +HTTP request preconditions 221

+

6.3.5 +JSON-LD @context resolution 222

+

6.3.6 +HTTP response common requirements 223

+

6.3.7 +Representation of Entities 223

+

6.3.8 +Notification behaviour 224

+

6.3.9 +Csource Notification behaviour 225

+

6.3.10 +Pagination behaviour 225

+

6.3.11 +Including system generated Temporal Attributes 226

+

6.3.12 +Simplified or aggregated temporal representation of Entities +227

+

6.3.13 +Counting number of results 227

+

6.3.14 +Tenant specification 228

+

6.3.15 +GeoJSON representation of spatially bound entities +228

+

6.3.16 +Expiration time for cached @contexts 228

+

6.3.17 +Distributed Operations Caching and Timeout Behaviour +228

+

6.3.18 +Limiting Distributed Operations 229

+

6.3.19 +Extra information to provide when contacting Context Source +230

+

6.3.20 +Invalid parameters 230

+

6.4 +Resource: entities/ 230

+

6.4.1 +Description 230

+

6.4.2 +Resource definition 230

+

6.4.3 +Resource methods 230

+

6.5 +Resource: entities/{entityId} 235

+

6.5.1 +Description 235

+

6.5.2 +Resource definition 235

+

6.5.3 +Resource methods 235

+

6.6 +Resource: entities/{entityId}/attrs/ 241

+

6.6.1 +Description 241

+

6.6.2 +Resource definition 241

+

6.6.3 +Resource methods 242

+

6.7 +Resource: entities/{entityId}/attrs/{attrId} 244

+

6.7.1 +Description 244

+

6.7.2 +Resource definition 244

+

6.7.3 +Resource methods 245

+

6.8 +Resource: csourceRegistrations/ 248

+

6.8.1 +Description 248

+

6.8.2 +Resource definition 248

+

6.8.3 +Resource methods 248

+

6.9 +Resource: csourceRegistrations/{registrationId} 251

+

6.9.1 +Description 251

+

6.9.2 +Resource definition 251

+

6.9.3 +Resource methods 252

+

6.10 +Resource: subscriptions/ 254

+

6.10.1 +Description 254

+

6.10.2 +Resource definition 254

+

6.10.3 +Resource methods 254

+

6.11 +Resource: subscriptions/{subscriptionId} 256

+

6.11.1 +Description 256

+

6.11.2 +Resource definition 256

+

6.11.3 +Resource methods 256

+

6.12 +Resource: csourceSubscriptions/ 258

+

6.12.1 +Description 258

+

6.12.2 +Resource definition 258

+

6.12.3 +Resource methods 258

+

6.13 +Resource: csourceSubscriptions/{subscriptionId} 260

+

6.13.1 +Description 260

+

6.13.2 +Resource definition 260

+

6.13.3 +Resource methods 260

+

6.14 +Resource: entityOperations/create 262

+

6.14.1 +Description 262

+

6.14.2 +Resource definition 263

+

6.14.3 +Resource methods 263

+

6.15 +Resource: entityOperations/upsert 264

+

6.15.1 +Description 264

+

6.15.2 +Resource definition 264

+

6.15.3 +Resource methods 265

+

6.16 +Resource: entityOperations/update 266

+

6.16.1 +Description 266

+

6.16.2 +Resource definition 267

+

6.16.3 +Resource methods 267

+

6.17 +Resource: entityOperations/delete 268

+

6.17.1 +Description 268

+

6.17.2 +Resource definition 268

+

6.17.3 +Resource methods 269

+

6.18 +Resource: temporal/entities/ 270

+

6.18.1 +Description 270

+

6.18.2 +Resource definition 270

+

6.18.3 +Resource methods 270

+

6.19 +Resource: temporal/entities/{entityId} 273

+

6.19.1 +Description 273

+

6.19.2 +Resource definition 273

+

6.19.3 +Resource methods 274

+

6.20 +Resource: temporal/entities/{entityId}/attrs/ 276

+

6.20.1 +Description 276

+

6.20.2 +Resource definition 277

+

6.20.3 +Resource methods 277

+

6.21 +Resource: temporal/entities/{entityId}/attrs/{attrId} +278

+

6.21.1 +Description 278

+

6.21.2 +Resource definition 278

+

6.21.3 +Resource methods 278

+

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

+

6.22.1 +Description 279

+

6.22.2 +Resource definition 279

+

6.22.3 +Resource methods 279

+

6.23 +Resource: entityOperations/query 281

+

6.23.1 +Description 281

+

6.23.2 +Resource definition 281

+

6.23.3 +Resource methods 281

+

6.24 +Resource: temporal/entityOperations/query 282

+

6.24.1 +Description 282

+

6.24.2 +Resource definition 282

+

6.24.3 +Resource methods 283

+

6.25 +Resource: types/ 283

+

6.25.1 +Description 283

+

6.25.2 +Resource definition 283

+

6.25.3 +Resource methods 283

+

6.26 +Resource: types/{type} 284

+

6.26.1 +Description 284

+

6.26.2 +Resource definition 285

+

6.26.3 +Resource methods 285

+

6.27 +Resource: attributes/ 286

+

6.27.1 +Description 286

+

6.27.2 +Resource definition 286

+

6.27.3 +Resource methods 286

+

6.28 +Resource: attributes/{attrId} 287

+

6.28.1 +Description 287

+

6.28.2 +Resource definition 287

+

6.28.3 +Resource methods 287

+

6.29 +Resource: jsonldContexts/ 288

+

6.29.1 +Description 288

+

6.29.2 +Resource definition 288

+

6.29.3 +Resource methods 288

+

6.30 +Resource: jsonldContexts/{contextId} 290

+

6.30.1 +Description 290

+

6.30.2 +Resource definition 290

+

6.30.3 +Resource methods 290

+

6.31 +Resource: entityOperations/merge 292

+

6.31.1 +Description 292

+

6.31.2 +Resource definition 292

+

6.31.3 +Resource methods 292

+

6.32 +Resource: entityMaps/{entityMapId} 294

+

6.32.1 +Description 294

+

6.32.2 +Resource definition 294

+

6.32.3 +Resource methods 294

+

6.33 +Resource: info/sourceIdentity 296

+

6.33.1 +Description 296

+

6.33.2 +Resource definition 296

+

6.33.3 +Resource methods 296

+

7 +API MQTT Notification Binding 297

+

7.1 +Introduction 297

+

7.2 +Notification behaviour 297

+

A.1 +Introduction 299

+

A.2 +Entity identifiers 299

+

A.3 +NGSI-LD namespace 299

+

C.1 +Introduction 306

+

C.2 +Entity Representation 306

+

C.2.1 +Property Graph 306

+

C.2.2 +Vehicle Entity 307

+

C.2.3 +Parking Entity 320

+

C.2.4 +@context 326

+

C.3 +Context Source Registration 326

+

C.4 +Context Subscription 327

+

C.5 +HTTP REST API Examples 328

+

C.5.1 +Introduction 328

+

C.5.2 +Create Entity of Type Vehicle 328

+

C.5.2.1 +HTTP Request 328

+

C.5.2.2 +HTTP Response 328

+

C.5.3 +Query Entities 328

+

C.5.3.1 +Introduction 328

+

C.5.3.2 +HTTP Request 328

+

C.5.3.3 +HTTP Response 328

+

C.5.4 +Query Entities (Pagination) 329

+

C.5.4.1 +Introduction 329

+

C.5.4.2 +HTTP Request 329

+

C.5.4.3 +HTTP Response 329

+

C.5.5 +Temporal Query 329

+

C.5.5.1 +Introduction 329

+

C.5.5.2 +HTTP Request #1 330

+

C.5.5.3 +HTTP Response #1 330

+

C.5.5.2 +HTTP Request #2 330

+

C.5.5.3 +HTTP Response #2 330

+

C.5.6 +Temporal Query (Simplified Representation) 331

+

C.5.6.1 +Introduction 331

+

C.5.6.2 +HTTP Request 331

+

C.5.6.3 +HTTP Response 331

+

C.5.7 +Retrieve Available Entity Types 332

+

C.5.7.1 +Introduction 332

+

C.5.7.2 +HTTP Request 332

+

C.5.7.3 +HTTP Response 332

+

C.5.8 +Retrieve Details of Available Entity Types 332

+

C.5.8.1 +Introduction 332

+

C.5.8.2 +HTTP Request 332

+

C.5.8.3 +HTTP Response 333

+

C.5.9 +Retrieve Available Entity Type Information 333

+

C.5.9.1 +Introduction 333

+

C.5.9.2 +HTTP Request 333

+

C.5.9.3 +HTTP Response 334

+

C.5.10 +Retrieve Available Attributes 334

+

C.5.10.1 +Introduction 334

+

C.5.10.2 +HTTP Request 334

+

C.5.10.3 +HTTP Response 335

+

C.5.11 +Retrieve Details of Available Attributes 335

+

C.5.11.1 +Introduction 335

+

C.5.11.2 +HTTP Request 335

+

C.5.11.3 +HTTP Response 335

+

C.5.12 +Retrieve Available Attribute Information 336

+

C.5.12.1 +Introduction 336

+

C.5.12.2 +HTTP Request 336

+

C.5.12.3 +HTTP Response 336

+

C.5.13 +Query Entities (Natural Language Filtering) 337

+

C.5.13.1 +Introduction 337

+

C.5.13.2 +HTTP Request 337

+

C.5.13.3 +HTTP Response 337

+

C.5.14 +Temporal Query (Aggregated Representation) 337

+

C.5.14.1 +Introduction 337

+

C.5.14.2 +HTTP Request 337

+

C.5.14.3 +HTTP Response 337

+

C.5.15 +Scope Queries 338

+

C.5.15.1 +Introduction 338

+

C.5.15.2 +HTTP Request 338

+

C.5.15.3 +HTTP Response 338

+

C.5.16 +Temporal Scope Queries 340

+

C.5.16.1 +Introduction 340

+

C.5.16.2 +HTTP Request 340

+

C.5.16.3 +HTTP Response 340

+

C.6 +Date Representation 341

+

C.7 +@context utilization clarifications 342

+

C.8 +Link header utilization clarifications 344

+

C.9 +@context processing clarifications 345

+

D.1 +Introduction 347

+

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

+

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

+

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

+

G.0 +Foreword 352

+

G.1 +Introduction 352

+

G.1.0 +Foreword 352

+

G.1.1 +Associating an Entity with a Natural Language 352

+

G.1.2 +Associating a Property with a Natural Language 352

+

G.1.3 +Associating as equivalent entity 353

+

G.2 +Natural Language Collation Support 353

+

G.2.0 +Foreword 353

+

G.2.1 +Maintain collations as metadata 354

+

G.2.2 +Route language sensitive queries via a proxy 354

+

G.3 +Localization of Dates, Currency formats, etc. 354

+

G.3.0 +Foreword 354

+

G.3.1 +Localizing Dates 354

+

H.1 +Actuators and feedback to the consumer 356

+

H.2 +Architecture for actuation 356

+

H.3 +Structure of Commands and additional Properties 357

+

H.3.0 +Introduction 357

+

H.3.1 +Property for listing available commands 358

+

H.3.2 +Properties for command endpoints 358

+

H.4 +Communication model 360

+

H.4.1 +Possible communication models 360

+

H.4.2 +Subscription/notification model 360

+

H.4.3 +Forwarding model 361

+

H.5 +Implementation of the subscription-based actuation workflow +362

+

H.6 +Implementation of the registration-based actuation workflow +363

+

History 369

+
+ + diff --git a/public/1-intellectual-property-rights.html b/public/1-intellectual-property-rights.html new file mode 100644 index 0000000000000000000000000000000000000000..fffab960e95be133ae06ed7a1d024c06203ce453 --- /dev/null +++ b/public/1-intellectual-property-rights.html @@ -0,0 +1,2797 @@ + + + + + + + Intellectual Property Rights + + + + + + + + +

Intellectual Property Rights

+
+Essential patents +
+

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.

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

+ + diff --git a/public/10-tabapi-operation-definition.html b/public/10-tabapi-operation-definition.html new file mode 100644 index 0000000000000000000000000000000000000000..63351e2dcb17d81ea81acce49549c9e1a4266cfd --- /dev/null +++ b/public/10-tabapi-operation-definition.html @@ -0,0 +1,23876 @@ + + + + + + + 5 API Operation Definition + + + + + + + + +

5 API Operation Definition

+

5.1 Introduction

+

This clause defines data structures and operations of the NGSI-LD +API. No specific binding is assumed. Clause 6 maps +these operations and data types to the HTTP REST binding.

+
+
+NOTE: +
+
+In + +UML + +diagrams + +dotted + +arrows + +denote + +a + +response + +to + +a + +request. +
+
+

5.2 Data Types

+

5.2.1 Introduction

+

Implementations shall support the data types defined by the clauses +below. For each member defined by each data type (including nested ones) +a term shall be added to the Core @context, as mandated by clause +4.5.

+

None of the members described admit a null value directly, as +when a JSON-LD processor encounters null, the associated entry or +value is always removed when expanding the JSON-LD document.

+

However, in the context of a partial update or merge operation (see +clauses 5.5.8 +and 5.5.12), +an NGSI-LD Null shall be used to indicate the removal of a target +member. Thus, for representing deleted elements in notifications and in +the temporal evolution, 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 LanguageProperty, respectively. In all +other cases, implementations shall raise an error of type +BadRequestData if an NGSI-LD Null value is encountered.

+

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

+

Non-normative JSON Schema [i.11] definitions of the +referred data types are also available at [i.13].

+

The use of URI in the context of the present document also includes +the use of International Resource Identifiers (IRIs) as defined in IETF +RFC 3987 [23], which +extends the use of characters to Unicode characters [22] beyond the ASCII +character set, enabling the support of languages other than English.

+

5.2.2 Common members

+

The JSON-LD representation of NGSI-LD Entity, Property, Relationship, +Context Source Registration and +Subscription can include the common members described by Table +5.2.2‑1.

+

Those members are read-only, and shall be automatically generated by +NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+

In query or retrieve operations implementations shall only generate +common members (Table +5.2.2‑1) when the Context +Consumer explicitly asks for their inclusion. Clause +6.3.11 defines the mechanism offered by the HTTP binding for such +purpose.

+
+Table 5.2.2-1: Common members of NGSI-LD elements +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+createdAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity creation timestamp. See clause +4.8 +
+modifiedAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity last modification timestamp. See clause +4.8 +
+deletedAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity deletion timestamp. See clause +4.8
+It is only used in notifications reporting deletions and in the temporal +representation of Entities (clause +4.5.6), Properties (clause +4.5.7), Relationships (clause +4.5.8) and LanguageProperties (clause +5.2.32) and VocabProperties (clause +5.2.35) and JsonProperties (clause +5.2.38) +
+

5.2.3 @context

+

When encoding NGSI-LD Entities, Context +Source Registrations, Subscriptions and Notifications, as pure +JSON-LD (MIME type "application/ld+json"), an array (flattened +to a single string if necessary), containing a user +@contextwhere present, and +the core @context (as described in clause +4.4) shall be included as a special member of the corresponding +JSON-LD Object. Table +5.2.3‑1 gives a precise definition of this special member.

+
+Table 5.2.3-1: JSON-LD @context tagged member +
+ +++++++ + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. +
+

5.2.4 Entity

+

This type represents the data needed to define an NGSI-LD Entity as +mandated by clause +4.5.1.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.4‑1.

+
+Table 5.2.4-1: NGSI-LD Entity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Entity ID. +
+type +
+String or String[] +
+ +
+1 +
+Entity Type(s). Both short hand string(s) (type name) or URI(s) are +allowed +
+ +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the Entity. See clause +4.22 +
+scope +
+String or String[] +
+See clause +4.18 +
+0..1 +
+Scope +
+location +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+Default geospatial Property of an entity. See clause +4.7 +
+observationSpace +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+See clause +4.7 +
+operationSpace +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+See clause +4.7 +
+<Property name> +
+Property or Property[] (see note 1) +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Property as mandated by clause +4.5.2 +
+GeoProperty or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperty as mandated by clause +4.5.2 +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperty as mandated by clause +4.5.18 +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperty as mandated by clause +4.5.24 +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperty as mandated by clause +4.5.20 +
+ListProperty or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperty as mandated by clause +4.5.21 +
+<Relationship name> +
+Relationship or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationship as mandated by clause +4.5.3 +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationship as mandated by clause +4.5.22 +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

5.2.5 Property

+

This type represents the data needed to define a Property as +mandated by clause +4.5.2.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.5‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type member can be omitted as type="Property" can be inferred from the +presence of the value member. Furthermore, in the concise +representation of a Property, the value member cannot be a +GeoJSON Object (as defined in clause +4.7) as it would be interpreted as a GeoProperty (see clause +5.2.7).

+
+Table 5.2.5-1: NGSI-LD Property data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Property" +
+1 +
+Node type. +
+value +
+Any JSON value as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Property Value. +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the Property. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+unitCode +
+String +
+As mandated by [15] +
+0..1 +
+Property Value's unit code +
+valueType +
+String +
+ +
+0..1 +
+The native JSON-LD @type for the Property Value. A String Value +which shall be type coerced to a URI based on the supplied +@context +
+<Property name> +
+Property or Property[] (see note 1) +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the Property +
+GeoProperty or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the Property +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the Property +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the Property +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the Property +
+ListProperty or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the Property +
+<Relationship name> +
+Relationship or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the Property +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the Property +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

The following output only members (defined by Table +5.2.5-2) of the Property data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.5-2: Output only members of the NGSI-LD Property data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of Properties +
+0..1 +
+URI uniquely identifying a Property instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousValue +
+Any JSON value as defined by IETF RFC 8259 [6] +
+Only used in Notifications, if the showChanges option is +explicitly requested +
+0..1 +
+Previous Property Value +
+

5.2.6 Relationship

+

This type represents the data needed to define a Relationship +as mandated by clause +4.5.3.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.6‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type +member can be omitted as type="Relationship" can be inferred from the +presence of the object member.

+
+Table 5.2.6-1: NGSI-LD Relationship data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Relationship" +
+1 +
+Node type +
+object +
+String or String[] +
+Valid URI or an Array of Valid URIs +
+1 +
+Relationship's target object +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of target relationship objects +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the Relationship. See clause +4.22 +
+objectType +
+String or String[] +
+ +
+0..1 +
+Node Type of the Relationship's target object. Both short hand string(s) +(type name) or URI(s) are allowed +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property or Property[] (see note 1) +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the Relationship +
+GeoProperty or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the Relationship +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the Relationship +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the Relationship +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the Relationship +
+ListProperty or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the Relationship +
+<Relationship name> +
+Relationship or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the Relationship +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the Relationship +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

The following output only members (defined by Table +5.2.6-2) of the Relationship data structure are also defined. +They are read-only and shall be generated by NGSI-LD implementations. +They shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.6-2: Output only members of the NGSI-LD Relationship data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+entity +
+Entity or Entity[] (see note) +
+See datatype definition in clause 5.2.4. +
+
+ +
+
+Only used in Linked Entity Retrieval, if the join=inline option +is explicitly requested +
+0..1 +
+An inline Entity obtained by Linked Entity Retrieval, corresponding to +the Relationship's target object. See clause +4.5.23.2 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of Relationships +
+0..1 +
+URI uniquely identifying a Relationship instance as mandated by clause +4.5.8 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousObject +
+String +
+Valid URI. Only used in Notifications, if the showChanges option +is explicitly requested +
+0..1 +
+Previous Relationship's target object +
+
+NOTE: +
+
+one-to-N + +Relationships + +expand + +to + +an + +array + +of + +Entity + +elements, + +since + +there + +can + +be + +more + +than + +one + +target + +object + +URI + +specified. +
+
+
+ +
+

5.2.7 GeoProperty

+

This type represents the data needed to define a +GeoProperty.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.7‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type member can be omitted as "GeoProperty" can be inferred from the presence +of the value member holding a GeoJSON Geometry as mandated +by clause +4.7.

+
+Table 5.2.7-1: NGSI-LD GeoProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "GeoProperty" +
+1 +
+Node type +
+value +
+JSON Object +
+As mandated by clause +4.7 +
+1 +
+Geolocation encoded as GeoJSON [8] +
+ +
+ +
+ +
+ +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the GeoProperty. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+valueType +
+String +
+ +
+0..1 +
+The native JSON-LD @type for the GeoProperty Value. A String +Value which shall be type coerced to a URI based on the supplied +@context +
+<Property name> +
+Property or Property[] (see note 1) +
See datatype definition in +clause 5.2.50..NProperties of the GeoProperty
+GeoProperty or GeoProperty[] (see note 1) +
See datatype definition in +clause 5.2.70..NGeoPropertiesof the GeoProperty
LanguageProperty or +LanguageProperty[] (see note +1)See datatype definition in +clause 5.2.320..NLanguagePropertiesof the GeoProperty
JsonProperty or +JsonProperty[] (see +note 1)See datatype +definition in clause 5.2.380..NJsonPropertiesof the GeoProperty
VocabProperty or +VocabProperty[] (see note 1)See datatype definition in +clause 5.2.350..NVocabPropertiesof the GeoProperty
+ListProperty or ListProperty[] (see note 1) +
See datatype definition in +clause 5.2.360..NListPropertiesof the GeoProperty
+<Relationship name> +
+Relationship or Relationship[] (see note 2) +
See datatype definition in +clause 5.2.60..NRelationships of the GeoProperty
ListRelationship or +ListRelationship[] +(see +note 2)See datatype definition in +clause 5.2.370..NListRelationshipsof the GeoProperty
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

The following output only members (defined by Table +5.2.7-2) of the GeoProperty data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.7-2: Output only members of the NGSI-LD GeoProperty data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of GeoProperties +
+0..1 +
+URI uniquely identifying a GeoProperty instance as mandated by clause +4.5.7. +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousValue +
+Any JSON value as defined by IETF RFC 8259 [6] +
+Only used in Notifications, if the +showChanges option is explicitly requested +
+0..1 +
+Previous GeoProperty Value. +
+

5.2.8 EntityInfo

+

This type represents what Entities, Entity Types or group of Entity +IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]) can be provided (by +Context Sources).

+

The JSON members shall follow the indications provided in Table +5.2.8‑1. id takes precedence over idPattern.

+

Notice that Cardinality of type being 1 implies that it is not +possible to register what Entities can be provided by a Context Source just by their id or +idPattern (i.e. without specifying their type).

+
+Table 5.2.8-1: EntityInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+0..1 +
+Entity identifier. +
+idPattern +
+String +
+Regular expression as per IEEE 1003.2™ [11] +
+0..1 +
+A regular expression which denotes a pattern that shall be matched by +the provided or subscribed Entities. +
+type +
+String or String[] +
+Fully Qualified Name of an Entity Type or the Entity Type name as a +short-hand string. See clause +4.6.2 +
+1 +
+Entity Type (or JSON array, in case of Entities with multiple Entity +Types). +
+

5.2.9 CSourceRegistration

+

This type represents the data needed to register a new Context Source.

+

The supported JSON members shall follow the indications provided in +Table +5.2.9‑1.

+
+Table 5.2.9-1: CSourceRegistration data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI. +
+
+Unique registration identifier. (JSON-LD @id). +
+0..1 +
+Generated at creation time, if it is not provided, it will be assigned +during registration process and returned to client. +
+
+It cannot be later modified in update operations. +
+type +
+String +
+It shall be equal to "ContextSourceRegistration" +
+1 +
+JSON-LD @type +
+
+Use reserved type for identifying Context Source Registration. +
+registrationName +
+String +
+Non-empty string +
+0..1 +
+A name given to this Context Source +Registration +
+contextSourceAlias +
+String +
+Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] +
+0..1 +
+A previously retrieved unique id for a registered Context Source which is used to identify +loops. +
+
+ +
+
+In the multi-tenancy use case (see clause +4.14), this id shall be used to identify a specific +Tenant within a registered Context Source. +
+description +
+String +
+Non-empty string +
+0..1 +
+A description of this Context Source +Registration. +
+information +
+RegistrationInfo[] +
+See data type definition in clause +5.2.10. Empty array (0 length) is not allowed +
+1 +
+Describes the Entities, Properties and Relationships for which the Context Source may be able to provide +information. +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of Attributes that the Context Source can provide, defined as per +clause +4.5.5. +
+tenant +
+String +
+ +
+0..1 +
+Identifies the Tenant that has to be +specified in all requests to the Context +Source that are related to the information registered in this +Context Source Registration. If not +present, the default Tenant is +assumed. Should only be present in systems supporting multi-tenancy. +
+observationInterval +
+TimeInterval +
+See data type definition in clause +5.2.11 +
+0..1 +
+If present, the Context Source can be +queried for Temporal Entity Representations. (If latest Entity +information is also provided, a separate Context Registration is needed +for this purpose). The observationInterval specifies the time +interval for which the Context Source +can provide Entity information as specified by the observedAt +Temporal Property. A temporal query based on the observedAt +Temporal Property, which is the default, is matched against the +observationInterval for overlap. +
+managementInterval +
+TimeInterval +
+See data type definition in clause +5.2.11 +
+0..1 +
+If present, the Context Source can be +queried for Temporal Entity Representations. (If latest Entity +information is also provided, a separate Context Registration is needed +for this purpose). The managementInterval specifies the time +interval for which the Context Source +can provide Entity information as specified by the createdAt, +modifiedAt and deletedAt Temporal Properties. A temporal +query based on the createdAt, modifiedAt or +deletedAt Temporal Property is matched against the +managementInterval for overlap. +
+location +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Location for which the Context +Source may be able to provide information. +
+observationSpace +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Geographic location that includes the observation spaces of all entities +as specified by their respective observationSpace +GeoProperty for which the Context +Source may be able to provide information. +
+operationSpace +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Geographic location that includes the operation spaces of all entities +as specified by their respective operationSpace +GeoProperty for which the Context +Source may be able to provide information. +
+expiresAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Provides an expiration date. When passed the Context Source Registration will become +invalid and the Context Source might +no longer be available. +
+endpoint +
+String +
+It shall be a dereferenceable URI +
+1 +
+Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD +interface. +
+contextSourceInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to convey optional information to provide +when contacting the registered Context +Source. +
+scope +
+String or +
+
+String[] +
+Scope(s) +
+0..1 +
+Scopes (see clause +4.18) for which the Context +Source has Entities. +
+mode +
+String +
+It shall be one of: +
+
+"inclusive", "exclusive", "redirect" or "auxiliary" +
+
+ +
+
+The mode is assumed to be "inclusive" if +not explicitly defined +
+0..1 +
+The definition of the mode of distributed operation (see clause +4.3.6) supported by the registered Context Source. +
+operations +
+String[] +
+Entries are limited to the named API operations and named operation +groups (see clause +4.20) +
+0..1 +
+The definition limited subset of API operations supported by the +registered Context Source. +
+
+ +
+
+If undefined, the default set of operations is "federationOps" (see clause +4.20). +
+refreshRate +
+String +
+String representing a duration in ISO 8601 format [17] +
+0..1 +
+An indication of the likely period of time to elapse between updates at +this registered endpoint. +
+
+ +
+
+Brokers may optionally use this information to help implement caching. +
+management +
+Registration +
+
+Management +
+
+Info +
+See data type definition in clause +5.2.34 +
+0..1 +
+Holds additional optional registration management information that can +be used to limit unnecessary distributed operation requests. +
+<CSource Property name> +
+Any JSON value as defined by IETF RFC 8259 [6] +
+ +
+0..N +
+Each Context Source Property pertains +to a characteristic of the Context +Source the Context Source +Registration describes. +
+

The members (defined by Table 5.2.9-2) of the +CSourceRegistration data structure are also defined. They are +read-only and shall be automatically generated by NGSI-LD +implementations. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.9-2: Additional members of the CSourceRegistration data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+status +
+String +
+Allowed values: +
+

"ok"

+

"failed"

+0..1 +
+Read-only., Status of the Registration. It shall be "ok" if the last attempt to perform a +distributed operation succeeded. It shall be "failed" if the last attempt to perform a +distributed operation failed. +
+timesSent +
+Number +
+0 or greater value +
+0..1 +
+Number of times that the +registration triggered a distributed operation, including failed +attempts. +
+timesFailed +
+Number +
+0 or greater value +
+0..1 +
+Number of times that the +registration triggered a distributed operation request that +failed. +
+lastSuccess +
+String +
+DateTime(clause 4.6.3) +
+0..1 +
+Timestamp corresponding to the +instant when the last successfully distributed operation was sent. +Created on first successful operation. +
lastFailure
+String +
+DateTime(clause 4.6.3) +
+0..1 +
Timestamp +corresponding to the instant when the last distributed operation +resulting in a failure (for +instance, in the +HTTP binding, an HTTP response code other than 2xx) was +returned.
+

5.2.10 RegistrationInfo

+

The supported JSON members shall follow the requirements provided in +Table +5.2.10‑1.

+
+Table 5.2.10-1: RegistrationInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entities +
+EntityInfo[] +
+See data type definition in clause +5.2.8. Empty array (0 length) is not allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the entities for which the CSource may be able to provide +information. +
+propertyNames +
+String[] +
+Property names as short hand strings or URIs. Empty array is not +allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the Properties that the CSource may be able to provide. +
+relationshipNames +
+String[] +
+Relationship names as short hand strings or URIs. Empty array is not +allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the Relationships that the CSource may be able to provide. +
+

At least one element of RegistrationInfo shall be present.

+

5.2.11 TimeInterval

+

The supported JSON members shall follow the requirements provided in +Table +5.2.11‑1.

+
+Table 5.2.11-1: TimeInterval data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+startAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Describes the start of the time interval +
+endAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Describes the end of the time interval. If not present the interval is +open +
+

5.2.12 Subscription

+

This datatype represents a Context Subscription.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.12‑1.

+
+Table 5.2.12-1: Subscription data type definition +
+ ++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+0..1 +
+Subscription identifier (JSON-LD @id). Generated at creation +time, if it is not provided, it will be assigned during subscription +process and returned to client. +
+
+It cannot be later modified in update operations. +
+type +
+String +
+It shall be equal to "Subscription" +
+1 +
+JSON-LD @type. +
+subscriptionName +
+String +
+ +
+0..1 +
+A (short) name given to this Subscription. +
+description +
+String +
+ +
+0..1 +
+Subscription description. +
+entities +
+EntitySelector[] +
+See data type definition in clause +5.2.33. Empty array (0 length) is not allowed. +
+
+ +
+
+Mandatory if timeInterval is present, unless the execution of the +request is limited to local scope (see clause +5.5.13) +
+0..1 +
+Entities subscribed. +
+watchedAttributes +
+String[] +
+Attribute name as short hand strings or URIs. Empty array (0 length) is +not allowed. +
+
+ +
+
+if timeInterval is present it shall not appear (0 cardinality) +
+0..1 +
+Watched Attributes (Properties or Relationships). If not defined it +means any Attribute. +
+localOnly +
+Boolean +
+ +
+0..1 +
+If localOnly=true then the subscription only pertains to the +Entities stored locally. +
+notificationTrigger +
+String[] +
+Valid notification triggers are "entityCreated", "entityUpdated", "entityDeleted", "attributeCreated", "attributeUpdated", "attributeDeleted" +
+0..1 +
+The notification triggers listed indicate what kind of changes shall +trigger a notification. If not present, the default is the combination +"attributeCreated" and "attributeUpdated". "entityUpdated" is equivalent to the +combination "attributeCreated", "attributeUpdated" and "attributeDeleted" +
+timeInterval +
+Number +
+Greater than 0 +
+
+if watchedAttributes is present it shall not appear (0 +cardinality) +
+0..1 +
+Indicates that a notification shall be delivered periodically regardless +of attribute changes. Actually, when the time interval (in seconds) +specified in this value field is reached. +
+q +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Query that shall be met by subscribed entities in order to trigger the +notification. +
+expandValues +
+String +
+Comma separated list of attribute names +
+0..1 +
+Values of the identified attributes should be expanded against the +supplied @context using JSON-LD type coercion prior to executing +the query. +
+jsonKeys +
+String +
+Comma separate list of attribute names +
+0..1 +
+Values of the identified attributes are to be considered uninterpretable +as JSON-LD and should not be expanded against the supplied +@context using JSON-LD type coercion prior to executing the +query. +
+geoQ +
+GeoQuery +
+See data type definition in clause 5.2.13 +
+0..1 +
+Geoquery that shall be met by subscribed entities in order to trigger +the notification. +
+csf +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Context source filter that shall be met by Context Source Registrations describing +Context Sources to be used for Entity +Subscriptions. +
+isActive +
+Boolean +
+true by default +
+0..1 +
+Allows clients to temporarily pause the subscription by making it +inactive. true indicates that the Subscription is under +operation. false indicates that the subscription is paused, and +notifications shall not be delivered. +
+notification +
+NotificationParams +
+See data type definition in clause +5.2.14 +
+1 +
+Notification details. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+Expiration date for the subscription. +
+throttling +
+Number +
+Greater than 0. Fractional values are allowed. If timeInterval is +present it shall not appear (0 cardinality) +
+0..1 +
+Minimal period of time in seconds which shall elapse between two +consecutive notifications. +
+temporalQ +
+TemporalQuery +
+See data type definition in clause +5.2.21 +
+0..1 +
+Temporal Query to be used only in +Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal +information. +
+scopeQ +
+String +
+See clause +4.19 +
+0..1 +
+Scope query. +
+lang +
+String +
+A natural language filter in the form of a IETF RFC 5646 [28] language code +
+0..1 +
+Language filter to be applied to the query (clause +4.15). +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of the Attribute instances to be selected for +each matched Attribute as per clause +4.5.5. +
+jsonldContext +
+String +
+Dereferenceable URI +
+ +
+The dereferenceable URI of the JSON-LD @context to be used when +sending a notification resulting from the subscription. If not provided, +the @context used for the subscription shall be used as a +default. +
+ngsildConformance +
+String +
+A semantically versioned string in the form major.minor, which +conforms to a version of the NGSI-LD specification +
+0..1 +
+If provided the notification shall undergo a backwards compatibility +operation as defined by clause +4.3.6.8 and be amended to conform to the supplied version of the +NGSI-LD specification. +
+splitEntities +
+Boolean +
+default decided by implementation; it should be configurable. The +parameter does not apply in case localOnly is true. +
+0..1 +
+If true it is assumed that single Entities are distributed +between different Context Brokers and/or Context Sources and this has to +be taken into account when applying any kind of filters (q, geoQ, +scopeQ, Attributes etc.). If false it is expected that Context +Broker and/or Context Source always have complete Entities, which allows +applying filters locally. +
+

At least one of (a) entities or (b) watchedAttributes +shall be present, unless the member localOnly +is set to true, in which case the execution of the request +is limited to local scope (see clause +5.5.13).

+

The members (defined by Table 5.2.12-2) of the Subscription +data structure are also defined. They are read-only and shall be +automatically generated by NGSI-LD implementations. They shall not be +provided by Context Subscribers. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore +them.

+
+Table 5.2.12-2: Additional members of the Subscription data type +
+ +++++++ + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+status +
+String +
+Allowed values: +
+

"active"

+

"paused"

+

"expired"

+0..1 +
+Read-only. Provided by the system when querying the details of a +subscription +
+

5.2.13 GeoQuery

+

This datatype represents a geoquery used for Subscriptions.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.13‑1.

+
+Table 5.2.13-1: GeoQuery data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+geometry +
+String +
+A valid GeoJSON [8] +geometry type excepting GeometryCollection +
+1 +
+
+ +
+Type of the reference geometry. +
+coordinates +
+JSON Array or String +
+A JSON Array coherent with the geometry type as per IETF RFC 7946 +[8] +
+1 +
+Coordinates of the reference geometry. For the sake of JSON-LD +compatibility It can be encoded as a string as described in clause +4.7.1. +
+georel +
+String +
+A valid geo-relationship as defined by clause +4.10 +
+1 +
+Geo-relationship ("near", "within", etc.). +
+geoproperty +
+String +
+Attribute name as short hand string or URI +
+0..1 +
+Specifies the GeoProperty to which the GeoQuery is to be applied. If not +present, the default GeoProperty is location. +
+

5.2.14 NotificationParams

+

5.2.14.1 NotificationParams +data type definition

+

This datatype represents the parameters that allow to convey the +details of a notification.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.14.1‑1.

+
+Table 5.2.14.1-1: NotificationParams data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+attributes +
+String[] +
+Attribute name as short hand strings or URIs. Empty array (0 length) is +not allowed +
+0..1 +
+A synonym for a combination of the pick andq parameter. +Deprecated +
+
+ +
+
+Attribute names to be included in the notification payload body. If +undefined it will mean all Attributes. +
+sysAttrs +
+Boolean +
+false by default +
+0..1 +
+If true, the system generated attributes createdAt and +modifiedAt and the system attribute expiresAt are included +in the response payload body, in the case of a deletion also +deletedAt. +
+format +
+String +
+It shall be one of: "normalized", "concise", "simplified" (or its synonym "keyValues") +
+0..1 +
+Conveys the representation format of the entities delivered at +notification time. By default, it will be in the normalized format. +
+pick +
+String[] +
+Entity member ("id", "type", "scope" +or a projected Attribute name as a valid attribute projection language +string as per clause +4.21). Empty array (0 length) is not allowed +
+0..1 +
+When defined, every Entity within the payload body is reduced down to +only contain the specified Entity members. +
+omit +
+String[] +
+Entity member ("id", "type", "scope" +or a projected Attribute name) as a valid attribute projection +language string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, the specified Entity members are removed from each Entity +within the payload. +
+showChanges +
+Boolean +
+false by default +
+0..1 +
+If true the previous value (previousValue) of +Properties or languageMap (previousLanguageMap) of +Language Properties or object (previousObject) of +Relationships is provided in addition to the current one. This requires +that it exists, i.e. in case of modifications and deletions, but not in +the case of creations. +
+
+showChanges cannot be true in case format is "keyValues". +
+join +
+String +
+It shall be one of: "flat", "inline", "@none" +
+0..1 +
+String representing the type of Linked +Entity retrieval to apply. +
+
+By default, it will be "@none". +
+joinLevel +
+Number +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. Default is 1. Only applicable if join parameter is "flat", or "inline". +
+endpoint +
+Endpoint +
+See data type definition in clause 5.2.15 +
+1 +
+Notification endpoint details. +
+

5.2.14.2 Output +only members

+

The following output only members (defined by Table +5.2.14.2-1) of the NotificationParams data structure are also +defined. They are read-only and shall be automatically generated by +NGSI-LD implementations. They shall not be provided by +Context Subscribers. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore +them.

+

In query or retrieve operations involving Subscriptions, +implementations shall generate them as part of their representation.

+
+Table 5.2.14.2-1: Output only members of the NotificationParams data +structure +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+timesSent +
+Number +
+Greater than 0 +
+0..1 +
+Number of times that the notification has been sent. Provided by the +system when querying the details of a subscription +
+timesFailed +
+Number +
+Greater than 0 +
+0..1 +
+Number of times an unsuccessful response (or timeout) has been received +when delivering the notification. Provided by the system when querying +the details of a subscription +
+lastNotification +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last notification has +been sent. Provided by the system when querying the details of a +subscription +
+lastFailure +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last notification +resulting in failure (for instance, in the HTTP binding, an HTTP +response code different than 200) has been sent. Provided by the system +when querying the details of a subscription +
+lastSuccess +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last successful (200 OK +response) notification has been sent. Provided by the system when +querying the details of a subscription +
+status +
+String +
+Allowed values: +
+
+"ok", "failed" +
+0..1 +
+Status of the Notification. It shall be "ok" if the last attempt to notify the +subscriber succeeded. It shall be "failed" if the last attempt to notify the +subscriber failed +
+

5.2.15 Endpoint

+

This datatype represents the parameters that are required in order to +define an endpoint for notifications. This can include, in addition the +endpoint's URI, a generic{key, value} array, named receiverInfo, +which contains, in a generalized form, whatever extra information the +Context Broker shall convey to the +receiver in order for the Context +Broker to successfully communicate with receiver (e.g. +Authorization material), or for the receiver to correctly interpret the +received content (e.g. the Link URL to fetch an @context). +Additionally, it can include another generic{key, value} array, named +notifierInfo, which contains the configuration that the Context Broker needs to know in order to +correctly set up the communication channel towards the receiver (e.g. +MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in clause +7.2).

+

The supported JSON members shall follow the indications provided in +Table +5.2.15‑1.

+
+Table 5.2.15-1: Endpoint data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+uri +
+String +
+Dereferenceable URI +
+1 +
+URI which conveys the endpoint which will receive the notification. +
+accept +
+String +
+MIME type. It shall be one of: +
+

"application/json"

+

"application/ld+json"

+

"application/geo+json"

+0..1 +
+Intended to convey the MIME type of the notification payload body (JSON, +or JSON-LD, or GeoJSON). If not present, default is "application/json". +
+timeout +
+Number +
+Greater than 0 +
+0..1 +
+Maximum period of time in +milliseconds which may elapse before a notification is assumed to have +failed. The NGSI-LD system can override this value. This only applies if +the binding protocol always returns a response. +
+cooldown +
+Number +
+Greater than 0 +
+0..1 +
Once a failure has +occurred, minimum period of time in milliseconds which shall elapse +before attempting to make a subsequent notification to the same endpoint +after failure.
+
+If requests are +received before the cooldown period has expired, no notification is +sent.
+receiverInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to convey optional information to the +receiver. +
+notifierInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to set up the communication channel. +
+

5.2.16 BatchOperationResult

+

This datatype represents the result of a batch operation.

+

The supported JSON members shall follow the indications provided in +Table +5.2.16‑1.

+
+Table 5.2.16-1: BatchOperationResult data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+success +
+String[] +
+Array of valid URIs +
+1 +
+Array of Entity IDs corresponding to the Entities that were successfully +treated by the concerned operation. Empty Array if no Entity was +successfully treated. +
+errors +
+BatchEntityError[] +
+ +
+1 +
+One array item per Entity in error. Empty Array if no errors happened. +
+

5.2.17 BatchEntityError

+

This datatype represents an error raised (associated to a particular +Entity) during the execution of a batch or distributed operation.

+

The supported JSON members shall follow the indications provided in +Table +5.2.17‑1.

+
+Table 5.2.17-1: BatchEntityError data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entityId +
+String +
+Valid URI +
+1 +
+Entity ID corresponding to the Entity in error +
+registrationId +
+String +
+Valid URI +
+0..1 +
+Registration Id corresponding to a failed distributed operation +(optional) +
+error +
+ProblemDetails (see IETF RFC 7807 [10]) +
+ +
+1 +
+One instance per Entity in error +
+

5.2.18 UpdateResult

+

This datatype represents the result of Attribute update (append or +update) operations in the NGSI-LD API regardless of whether local or +distributed.

+

The supported JSON members shall follow the indications provided in +Table +5.2.18‑1.

+
+Table 5.2.18-1: UpdateResult data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+updated +
+String[] +
+ +
+1 +
+List of Attributes (represented by their name) that were appended or +updated. +
+notUpdated +
+NotUpdatedDetails[] +
+See clause +5.2.19 +
+1 +
+List which contains the Attributes (represented by their name) that were +not updated, together with the reason for not being updated. +
+

5.2.19 NotUpdatedDetails

+

This datatype represents additional information provided by an +implementation when an Attribute update did not happen. See also clause +5.2.18.

+

The supported JSON members shall follow the indications provided in +Table +5.2.19‑1.

+
+Table 5.2.19-1: NotUpdatedDetails data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+attributeName +
+String +
+ +
+1 +
+Attribute name +
+reason +
+String +
+ +
+1 +
+Reason for not having changed such Attribute +
+registrationId +
+String +
+Valid URI +
+0..1 +
+Registration Id corresponding to a failed distributed operation +(optional) +
+

5.2.20 EntityTemporal

+

This datatype represents the Temporal +Evolution of an Entity.

+

This is the same datatype as mandated by clause 5.2.4 +with the only deviation that the representation of Properties and +Relationships shall be the temporal one (arrays of (Property or +Relationship) instances represented by JSON-LD objects) as +defined in clauses 4.5.7 +and 4.5.8. +Alternatively it is possible to specify the EntityTemporal by using the +"Simplified temporal representation of an Entity", as defined in clause +4.5.9.

+

5.2.21 TemporalQuery

+

This datatype represents a temporal query.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.21‑1.

+
+Table 5.2.21-1: TemporalQuery data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+timerel +
+String +
+Allowed values: "before", "after" and "between" +
+1 +
+Represents the temporal relationship as defined by clause +4.11 +
+timeAt +
+String representing the timeAt parameter as defined by clause +4.11 +
+It shall be a DateTime +
+1 +
+ +
+endTimeAt +
+String representing the endTimeAt parameter as defined by clause +4.11 +
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between" +
+0..1 +
+ +
+timeproperty +
+String representing a Temporal Property name +
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8) +
+0..1 +
+ +
+

5.2.22 KeyValuePair

+

This datatype represents the optional information that is required +when contacting an endpoint for notifications.

+

The supported members shall follow the indications provided in Table +5.2.22‑1. They are intended to represent a key/value pair.

+

Example optional information includes additional HTTP Headers such +as:

+
    +
  • +The HTTP Authentication Header. +
    • +
  • +The HTTP Prefer Header (IETF RFC 7240 [26]) used when notifying the +GeoJSON Endpoint. +
    • +
+
+Table 5.2.22-1: KeyValuePair data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+key +
+String +
+Binding-dependent +
+1 +
+The key of the key/value pair +
+value +
+String +
+Binding-dependent +
+1 +
+The value of the key/value pair +
+

5.2.23 Query

+

This datatype represents the information that is required in order to +convey a query when a "Query Entities" operation or a "Query Temporal +Evolution of Entities" operation is to be performed (as per clauses 5.7.2 +and 5.7.4, +respectively).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.23‑1.

+
+Table 5.2.23-1: Query data type definition +
+ ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Query" +
+1 +
+JSON-LD @type +
+entities +
+EntitySelector[] +
+See data type definition in clause +5.2.33. Empty array (0 length) is not allowed +
+0..1 +
+Entity IDs, id pattern and Entity types that shall be matched by +Entities in order to be retrieved. +
+attrs +
+String[] +
+Attribute name as short hand strings or URIs. +
+
+Empty array (0 length) is not allowed +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+List of Attributes that shall be matched by Entities in order to be +retrieved. If not present all Attributes will be retrieved. +
+pick +
+String[] +
+Entity member ("id", "type", "scope" or a +projected Attribute name) as a valid attribute projection language +string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, every Entity within the payload body is reduced down to +only contain the specified Entity members. +
+omit +
+String[] +
+Entity member ("id", "type", "scope" or a +projected Attribute name) as a valid attribute projection language +string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, the specified Entity members are removed from each Entity +within the payload. +
+q +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Query that shall be matched by Entities in order to be retrieved. +
+expandValues +
+String +
+Comma separated list of attribute names +
+0..1 +
+Values of the identified attributes should be expanded against the +supplied @context using JSON-LD type coercion prior to executing +the query. +
+jsonKeys +
+String +
+Comma separate list of attribute names +
+0..1 +
+Values of the identified attributes are to be considered uninterpretable +as JSON-LD and should not be expanded against the supplied +@context using JSON-LD type coercion prior to executing the +query. +
+geoQ +
+GeoQuery +
+See data type definition in clause 5.2.13 +
+0..1 +
+Geoquery that shall be matched by Entities in order be retrieved. +
+csf +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Context source filter that shall be matched by Context Source Registrations describing +Context Sources to be used for +retrieving Entities. +
+temporalQ +
+TemporalQuery +
+See data type definition in clause +5.2.21 +
+0..1 +
+Temporal Query to be present only for "Query Temporal Evolution of Entities" operation +(clause +5.7.4). +
+scopeQ +
+String +
+See clause +4.19 +
+0..1 +
+Scope query. +
+lang +
+String +
+A natural language filter in the form of a IETF RFC 5646 [28] language code +
+0..1 +
+Language filter to be applied to the query (clause +4.15). +
+containedBy +
+String[] +
+Comma separated list of URIs. Empty array (0 length) is not allowed +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. +
+
+ +
+
+Only applicable if joinLevel is present. +
+
+ +
+
+Only applicable for the "Query Entities" operation (clause +5.7.2). +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of the Attribute instances to be selected for +each matched Attribute as per clause +4.5.5. +
+entityMap +
+Boolean +
+ +
+0..1 +
If true, the location of the EntityMap used in the operation +is returned in the response. [{[--TAL--]}] [{[--TAL--]}]
+entityMapLifetime +
+String +
+String representing a duration in ISO 8601 format [17] +
+0..1 +
+Suggested duration for which the requester wants the EntityMap to exist. +The actual expiresAt time of the EntityMap shall be set by the Context +Broker or Context Source, possibly overriding the requested duration. +Only applicable if entityMap is set to true. +
+splitEntities +
+Boolean +
+default decided by implementation; it should be configurable. The +parameter does not apply in case the parameter local is +true. +
+0..1 +
+If true it is assumed that single Entities are distributed +between different Context Brokers and/or Context Sources and this has to +be taken into account when applying any kind of filters (q, geoQ, +scopeQ, Attributes etc.). If false it is expected that Context +Broker and/or Context Source always have complete Entities, which allows +applying filters locally. +
+

5.2.24 EntityTypeList

+

This type represents the data needed to define the entity type list +representation as mandated by clause +4.5.10.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.24‑1.

+
+Table 5.2.24-1: NGSI-LD EntityTypeList data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+URI that is unique within the system scope. Identifier for the entity +type list +
+type +
+String +
+It shall be equal to "EntityTypeList" +
+1 +
+JSON-LD @type +
+typeList +
+String[] +
+ +
+1 +
+List containing the entity type names +
+

5.2.25 EntityType

+

This type represents the data needed to define the elements of the +detailed entity type list representation as mandated by clause +4.5.11.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.25‑1.

+
+Table 5.2.25-1: NGSI-LD EntityType data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Fully Qualified Name (FQN) of the entity type being described +
+type +
+String +
+It shall be equal to "EntityType" +
+1 +
+JSON-LD @type +
+typeName +
+String +
+ +
+1 +
+Name of the entity type, short name if contained in @context +
+attributeNamenames +
+String[] +
+ +
+1 +
+List containing the names of attributes that instances of the entity +type can have +
+

5.2.26 EntityTypeInfo

+

This type represents the data needed to define the detailed entity +type information representation as mandated by clause +4.5.12.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.26‑1.

+
+Table 5.2.26-1: NGSI-LD EntityTypeInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Fully Qualified Name (FQN) of the entity type being described +
+type +
+String +
+It shall be equal to "EntityTypeInfo" +
+1 +
+JSON-LD @type +
+typeName +
+String +
+ +
+1 +
+Name of the entity type, short name if contained in @context +
+entityCount +
+Number +
+Unsigned integer +
+1 +
+Number of entity instances of this entity type +
+attributeDetails +
+Attribute[] +
+See data type definition in clause +5.2.28. Attribute with only the elements "id", "type", +"attributeName" and "attributeTypes" +
+1 +
+List of attributes that entity instances with the specified entity type +can have +
+

5.2.27 AttributeList

+

This type represents the data needed to define the attribute list +representation as mandated by clause +4.5.13.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.27‑1.

+
+Table 5.2.27-1: NGSI-LD AttributeList data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+URI that is unique within the system scope. Identifier for the attribute +list +
+type +
+String +
+It shall be equal to "AttributeList" +
+1 +
+JSON-LD @type +
+attributeList +
+String[] +
+ +
+1 +
+List containing the attribute names +
+

5.2.28 Attribute

+

This type represents the data needed to define the attribute +information needed as:

+
    +
  • +part of the entity type information representation as mandated by clause +4.5.12; +
    • +
  • +the detailed attribute list representation as mandated by clause +4.5.14; +
    • +
  • +the attribute information representation as mandated by clause +4.5.15. +
    • +
+

The supported JSON members shall follow the requirements provided in +Table +5.2.28‑1.

+
+Table 5.2.28-1: NGSI-LD Attribute data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Full URI of attribute name +
+type +
+String +
+It shall be equal to "Attribute" +
+1 +
+JSON-LD @type +
+attributeName +
+String +
+ +
+1 +
+Name of the attribute, short name if contained in @context +
+attributeCount +
+Number +
+Unsigned integer +
+0..1 +
+Number of attribute instances with this attribute name +
+attributeTypes +
+String[] +
+ +
+0..1 +
+List of attribute types (e.g. Property, Relationship, +GeoProperty) for which entity instances exist, which contain an +attribute with this name +
+typeNames +
+String[] +
+ +
+0..1 +
+List of entity type names for which entity instances exist containing +attributes that have the respective name +
+

5.2.29 Feature

+

This data type represents a spatially bounded Entity in GeoJSON +format, as mandated by IETF RFC 7946 [8]. The supported JSON members +shall follow the requirements provided in Table +5.2.29‑1.

+
+Table 5.2.29-1: Feature data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Entity ID +
+type +
+String +
+It shall be equal to "Feature" +
+1 +
+GeoJSON Type +
+geometry +
+GeoJSON Object +
+The value field from the matching GeoProperty (as specified in clause +4.5.16) or null +
+1 +
+null if no matching GeoProperty +
+properties +
+FeatureProperties +
+See data type definition +
+1 +
+List of attributes as mandated by clause +5.2.31 +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. This field is only present if requested in the +payload by the HTTP Prefer Header (IETF RFC 7240 [26]) +
+

5.2.30 FeatureCollection

+

This data type represents a list of spatially bounded Entities in +GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members +shall follow the requirements provided in Table +5.2.30‑1.

+
+Table 5.2.30-1: FeatureCollection data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "FeatureCollection" +
+1 +
+GeoJSON Type +
+features +
+Feature[] +
+See data type definition +
+1..N +
+In the case that no matches are found, features will be an empty +array +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. This field is only present if requested in the +payload by the HTTP Prefer Header (IETF RFC 7240 [26]) +
+

5.2.31 FeatureProperties

+

This data type represents the type and the associated attributes +(Properties and Relationships) of an Entity in GeoJSON +format.

+
+Table 5.2.31-1: NGSI-LD Entity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String or String[] +
+Entity Type +
+1 +
+Entity Type (or JSON array, in case of Entities with multiple Entity +Types). Both short hand string (type name) or URI are allowed. +
+<Property name> +
+
+ +
+Property or Property[], see note 1. +
+See data type definition in clause 5.2.5 +
+0..N +
+Property as mandated by clause +4.5.2. +
+GeoProperty or GeoProperty[], see note 1. +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperty as mandated by clause +4.5.2. +
+LanguageProperty or LanguageProperty[], see note 1. +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperty as mandated by clause +4.5.18. +
+JsonProperty or JsonProperty[] see note 1. +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties as mandated by clause +4.5.24. +
+VocabProperty or VocabProperty[], see note 1. +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperty as mandated by clause +4.5.20. +
+ListProperty or ListProperty[], see note 1. +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperty as mandated by clause +4.5.21. +
+<Relationship name> +
+
+ +
+Relationship or Relationship[], see note 2.2 +
+See data type definition in clause +5.2.6 +
+0..N +
+Relationship as mandated by clause +4.5.3. +
+ListRelationship or ListRelationship[], see note 2. +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationship as mandated by clause +4.5.22. +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

5.2.32 LanguageProperty

+

This type represents the data needed to define a +LanguageProperty as mandated by clause +4.5.18. Note that in case of concise representation, the type +can be omitted (see clause +4.5.18.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.32‑1.

+
+Table 5.2.32-1: NGSI-LD LanguageProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+string +
+It shall be equal to "LanguageProperty" +
+1 +
+Node type. +
+languageMap +
+JSON object +
+A set of key-value pairs whose keys shall be strings representing IETF +RFC 5646 [28] +language codes and whose values shall be JSON strings or arrays of JSON +strings +
+1 +
+String Property Values defined in multiple natural languages. +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the LanguageProperty. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8. +
+valueType +
+String +
+It shall be equal to “langString” (see note 1) +
+0..1 +
+The native JSON-LD @type for the languageMap attribute.It +shall align with the RDF datatype [33]. +
+<Property name> +
+
+ +
+Property or Property[] (see note 2) +
+See datatype definition in clauses 5.2.5 +
+0..N +
+Properties of the LanguageProperty. +
+GeoProperty +
+
+or GeoProperty[] (see note 2) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the LanguageProperty. +
+LanguageProperty or LanguageProperty[] (see note 2) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the LanguageProperty. +
+JsonProperty or JsonProperty[] (see note 2) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the LanguageProperty. +
+VocabProperty or VocabProperty[] (see note 2) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the LanguageProperty. +
+ListProperty +
+
+or ListProperty[] (see note 2) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the LanguageProperty. +
+<Relationship name> +
+Relationship +
+
+or Relationship[] (see note 3) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the LanguageProperty. +
+ListRelationship or ListRelationship[] (see note 3) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the LanguageProperty. +
+
+NOTE 1: +
+
+1: + +The + +assigned + +@type + +for + +language + +tagged + +strings + +is + +datatype + +URI: + +http://www.w3.org/1999/02/22-rdf-syntax-ns#langString + +[34] +
+
+
+
+NOTE 2: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 3: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

The following output only members (defined by Table +5.2.32-2) of the LanguageProperty data structure are also +defined. They are read-only and shall be generated by NGSI-LD +implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+
+Table 5.2.32-2: Output only members of the NGSI-LD LanguageProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of LanguageProperties +
+0..1 +
+URI uniquely identifying a LanguageProperty instance as mandated by clause +4.5.7. +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousLanguageMap +
+JSON object +
+A set of key-value pairs whose keys shall be strings representing IETF +RFC 5646 [28] +language codes and whose values shall be JSON strings. +
+
+Only used in Notifications, if the showChanges option is +explicitly requested +
+0..1 +
+Previous Language Property's languageMap. +
+

5.2.33 EntitySelector

+

This type selects which entity or group of entities are queried or +subscribed to by Context Consumers. +Entities can be specified by their id, Entity Types or group of Entity +IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]).

+

The JSON members shall follow the indications provided in Table +5.2.33‑1. id takes precedence over idPattern.

+
+Table 5.2.33-1: EntitySelector data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String or String[] +
+Valid URI(s) +
+0..1 +
+Entity identifier(s). +
+idPattern +
+String +
+Regular expression as per IEEE 1003.2™ [11] +
+0..1 +
+A regular expression which denotes a pattern that shall be matched by +the provided or subscribed Entities. +
+type +
+String +
+A valid type selection string as per clause +4.17. To indicate a request for all Entities (with implied local +scope), "*" is +also allowed as a value. +
+1 +
+Selector of Entity Type(s);
+If type is specified as "*", +implying local scope, local scope shall not be explicitly set to be +false (clause +5.5.13) for the execution of the corresponding operation. +
+

5.2.34 RegistrationManagementInfo

+

This type represents the data to alter the default behaviour of a +Context Broker when making a +distributed operation request to a registered Context Source. The supported JSON members +shall follow the indications provided in Table +5.2.34‑1. Brokers may override these recommendations.

+
+Table 5.2.34-1: RegistrationManagementInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+localOnly +
+Boolean +
+ +
+0..1 +
+If localOnly=true then distributed operations associated to this +Context Source Registration will act +only on data held directly by the registered Context +
+
+Source itself (see clause +4.3.6.4). +
+cacheDuration +
+String +
+String representing a duration in ISO 8601 [17] format +
+0..1 +

Minimal period of +time which shall elapse between two consecutive context information +consumption operations (as defined in clause 5.7) related to the same context +data will occur.

+

If the +cacheDurationlatency period has not been +reached, a cached value for the entity or its attributes shall be +returned where available.

+timeout +
+Number +
+Greater than 0 +
+0..1 +
+Maximum period of time in milliseconds which may elapse before a +forwarded request is assumed to have failed. +
+cooldown +
+Number +
+Greater than 0 +
+0..1 +

Minimum period of +time in milliseconds which shall elapse before attempting to make a +subsequent forwarded request to the same endpoint after +failure.

+

If requests are +received before the cooldown period has expired, a timeout error +response for the registration is automatically returned.

+

5.2.35 VocabProperty

+

This type represents the data needed to define a VocabProperty as mandated by clause +4.5.20. In case of concise representation, the type can be +omitted (see clause +4.5.20.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.35‑1.

+
+Table 5.2.35-1: NGSI-LD VocabularyProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "VocabProperty" +
+1 +
+Node type. +
+vocab +
+String or string[] +
+ +
+1 +
+String Values which shall be type coerced to URIs based on the supplied +@context. +
+ +
+datasetId +
+
+ +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the VocabProperty. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8. +
+valueType +
+String +
+ +
+0..1 +
+The native JSON-LD @type for the vocab attribute. A String +Value which shall be type coerced to a URI based on the supplied +@context. +
+<Property name> +
+Property +
+
+or Property[] (see note 1) +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Properties of the VocabProperty. +
+GeoProperty +
+
+or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the VocabProperty. +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the VocabProperty. +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the VocabProperty. +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the VocabProperty. +
+ListProperty +
+
+or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the VocabProperty. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the VocabProperty. +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the VocabProperty. +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+ +
+

The following output only members (defined by Table +5.2.35-2) of the VocabProperty data +structure are also defined. They are read-only and shall be generated by +NGSI-LD implementations. They shall not be provided by +Context Producers. In the event that they are provided (in update +or create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.35-2: Output only members of the NGSI-LD VocabProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of VocabProperties +
+0..1 +
+URI uniquely identifying a VocabProperty instance as mandated by clause +4.5.7. +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousVocab +
+String or String[] +
+Only used in Notifications +
+0..1 +
+Previous VocabProperty's vocab. +
+
+ +
+

5.2.36 ListProperty

+

This type represents the data needed to define a ListProperty +as mandated by clause +4.5.21. Note that in case of concise representation, the type +can be omitted (see clause +4.5.21.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.36‑1.

+
+Table 5.2.36-1: NGSI-LD ListProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to"ListProperty" +
+1 +
+Node type. +
+valueList +
+An array of JSON values as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Ordered array of Property Values. +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property list values +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the ListProperty. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8. +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property list values. +
+valueType +
+String +
+ +
+0..1 +
+The native JSON-LD @type for the valueList attribute. A +String Value which shall be type coerced to a URI based on the supplied +@context. +
+<Property name> +
+Property +
+
+or Property[] (see note 1) +
+See datatype definition in clauses 5.2.5 +
+0..N +
+Properties of the ListProperty. +
+GeoProperty +
+
+or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the ListProperty. +
+LanguageProperty +
+
+or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the ListProperty. +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the ListProperty. +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the ListProperty. +
+ListProperty +
+
+or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the ListProperty. +
+<Relationship name> +
+Relationship +
+
+or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the ListProperty. +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the ListProperty. +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+ +
+

The following output only members (defined by Table +5.2.36-2) of the ListProperty data structure are also defined. +They are read-only and shall be generated by NGSI-LD implementations. +They shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.36-2: Additional members of the NGSI-LD ListProperty data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of ListProperties +
+0..1 +
+URI uniquely identifying a ListProperty instance as mandated by clause +4.5.7. +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousValueList +
+An array of JSON values as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Ordered array of previous Property Values. +
+

5.2.37 ListRelationship

+

This type represents the data needed to define a +ListRelationship as mandated by clause +4.5.22. Note that in case of concise representation, the type +can be omitted (see clause +4.5.22.3) and the objectList may also be represented as an +ordered array of Strings.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.37‑1.

+
+Table 5.2.37-1: NGSI-LD ListRelationship data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "ListRelationship" +
+1 +
+Node type +
+objectList +
+JSON Object[] or +
+
+String[] +
+
+ +

In the normalized form, each +array element holds a JSON object containing a single Attribute with a +key called "object"and where the value is a valid +URI.

+
+In the concise form, each string in the array holds a valid URI +
+1 +
+Ordered array of Relationship target objects. +
+
+ +
+
+ +
+
+ +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of relationship list objects. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the ListRelationship. See clause +4.22 +
+objectType +
+String or String [] +
+ +
+0..1 +
+Node Type of the Relationship's target object. +
+
+Both short hand string(s) (type name) or URI(s) are allowed. +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8. +
+<Property name> +
+Property or Property[] (see note 1) +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the ListRelationship. +
+GeoProperty +
+
+or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the ListRelationship. +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the ListRelationship. +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the ListProperty. +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the ListRelationship. +
+ListProperty +
+
+or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the ListRelationship. +
+<Relationship name> +
+
+ +
+Relationship or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the ListRelationship. +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the ListRelationship. +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+

The following output only members (defined by Table +5.2.37-2) of the ListRelationship data structure are also +defined. They are read-only and shall be generated by NGSI-LD +implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+
+Table 5.2.37-2: Additional members of the NGSI-LD ListRelationship data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+entityList +
+Entity[] +
+See datatype definition in clause 5.2.4 +
+
+ +
+
+Only used in Linked Entity Retrieval, +if the join=inline option is explicitly requested +
+0..1 +
+An array of inline Entities obtained by Linked Entity retrieval, corresponding to +the ListRelationship's target objects See clause +4.5.23.2. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of +ListRelationships +
+0..1 +
+URI uniquely identifying a ListRelationship instance as mandated +by clause +4.5.8. +
+modifiedAt +
+String +
DateTime (clause 4.6.3)
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousObjectList +
+JSON Object[] or +
+
+String[] +
+
+ +

In the normalized form, each +array element holds a JSON object containing a containing a single +Attribute with a key called "object"and +where the value is a valid URI.

+
+In the concise form, each string in the array holds a valid URI +
+0..1 +
+Ordered array of previous Relationship target objects. +
+

5.2.38 JsonProperty

+

This type represents the data needed to define a JsonProperty as +mandated by clause +4.5.24. In case of concise representation, the type can be +omitted (see clause +4.5.24.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.38‑1.

+
+Table 5.2.38-1: NGSI-LD JsonProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "JsonProperty" +
+1 +
+Node type. +
+json +
+JSON +
+ +
+1 +
+Raw unexpandable JSON which shall not be interpreted as JSON-LD using +the supplied @context. +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+System temporal Property representing the expiration date for the +storage of the JsonProperty. See clause +4.22 +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8. +
+valueType +
+String +
+ +
+0..1 +
+The native JSON-LD @type for the json attribute. A String +Value which shall be type coerced to a URI based on the supplied +@context. +
+<Property name> +
+Property +
+
+or Property[] (see note 1) +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Properties of the JsonProperty. +
+GeoProperty +
+
+or GeoProperty[] (see note 1) +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the JsonProperty. +
+LanguageProperty or LanguageProperty[] (see note 1) +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the JsonProperty. +
+JsonProperty or JsonProperty[] (see note 1) +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the JsonProperty. +
+VocabProperty or VocabProperty[] (see note 1) +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the JSONPropertry. +
+ListProperty +
+
+or ListProperty[] (see note 1) +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the JsonProperty. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[] (see note 2) +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the JsonProperty. +
+ListRelationship or ListRelationship[] (see note 2) +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the JsonProperty. +
+
+NOTE 1: +
+
+For + +each + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+
+NOTE 2: +
+
+For + +each + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name, + +there + +can + +be + +one + +or + +more + +instances + +separated + +by + +datasetId. +
+
+
+ +
+

The following output only members (defined by Table +5.2.38-2) of the JsonProperty data structure are also defined. They are +read-only and shall be generated by NGSI-LD implementations. They shall +not be provided by Context Producers. In the event that they are +provided (in update or create operations) NGSI-LD implementations shall +ignore them.

+
+Table 5.2.38-2: Output only members of the NGSI-LD JsonProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8. +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8. +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of JsonProperties +
+0..1 +
+URI uniquely identifying a JsonProperty instance as mandated by clause +4.5.7. +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8. +
+previousJson +
+JSON +
+Only used in Notifications +
+0..1 +
+Previous JsonProperty's json. +
+
+ +
+

5.2.39 EntityMap

+

This type represents the data needed to define an EntityMap as +mandated by clause +4.5.25.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.39‑1.

+
+Table 5.2.39-1: NGSI-LD EntityMap data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+EntityMap ID. +
+type +
+String +
+It shall be equal to "EntityMap" +
+1 +
+Node type. +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+1 +
+Expiration date for the EntityMap. +
+

The following output only members (defined by Table +5.2.39-2) of the EntityMap data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by ContextConsumers. In the event that they are +provided in update operations NGSI-LD implementations shall ignore +them.

+
+Table 5.2.39-2: Additional members of the NGSI-LD EntityMap data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entityMap +
+JSON +
+A set of key-value pairs whose keys shall be strings representing Entity +ids and whose values shall be an array holding every CSourceRegistration +id which is relevant to the ongoing Context Information Consumption +request (see clause +4.21). +
+
+ +
+
+The key "@none" shall be used to refer to +an Entity that is held locally +
+1 +
+System generated mapping of Entities to CSourceRegistrations. +
+
+ +
+
+ +
+linkedMaps +
+JSON +
+A set of key-value pairs whose keys shall be strings representing +CSourceRegistration ids which are relevant to the ongoing Context +Information request and whose values shall represent the associated +EntityMap id used by the ContextSource. +
+1 +
+System generated mapping of Context CSourceRegistrations to a URI +indicating which EntityMaps was used by the Context Source. +
+
+ +
+

5.2.40 Context +Source Identity

+

This type represents the data uniquely identifying a Context Source, and if the Context Source supports multi-tenancy (see +clause +4.14) uniquely identifying a Tenant within that Context Source.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.40‑1.

+
+Table 5.2.40-1: Context Source Identity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Context Source ID. +
+type +
+String +
+It shall be equal to "ContextSourceIdentity" +
+1 +
+Node type. +
+ +
+contextSourceExtras +
+JSON +
+ +
+0..1 +
+Instance specific information relevant to the configuration of the Context Source itself in raw unexpandable +JSON which shall not be interpreted as JSON-LD using the supplied +@context. +
+contextSourceUptime +
+String +
+String representing a duration in ISO 8601 [17] format +
+1 +
+Total Duration that the Context +Source has been available. +
+contextSourceTimeAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Current time observed at the Context +Source. Timestamp See clause +4.8. +
+contextSourceAlias +
+String +
+Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] +
+1 +
+A unique id for a Context Source +which can be used to identify loops. +
+
+ +
+
+In the multi-tenancy use case (see clause +4.14), this id shall be identify a specific Tenant within a registered Context Source. +
+
+ +
+

5.3 Notification +data types

+

5.3.1 Notification

+

This datatype represents the parameters that allow building a +notification to be sent to a subscriber. How to build this notification +is detailed in clause +5.8.6.

+

The supported JSON members shall follow the indications provided in +Table +5.3.1‑1.

+
+Table 5.3.1-1: Notification data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Notification identifier (JSON-LD @id). It shall be automatically +generated by the implementation. +
+type +
+String +
+It shall be equal to "Notification" +
+1 +
+JSON-LD @type. +
+subscriptionId +
+String +
+Valid URI +
+1 +
+Identifier of the subscription that originated the notification. +
+notifiedAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Timestamp corresponding to the instant when the notification was +generated by the system. +
+data +
+NGSI-LD Entity[] or FeatureCollection +
+ +
+1 +
+The content of the notification as NGSI-LD Entities.
+See clause +5.2.4. +
+
+ +
+
+If the notification has been triggered from a Subscription that has the +notification. +
+
+endpoint.accept field set to application/geo+json then data is returned as a +FeatureCollection. In this case, if the +notification.endpoint.receiverInfo contains the key "Prefer" and it is set to the value "body=json", then the FeatureCollection +will not contain an @context field. +
+
+ +
+
+If endpoint.accept is not set or holds another value then +Entity[] is returned. +
+

5.3.2 CSourceNotification

+

This datatype represents the parameters that allow building a Context Source Notification to be sent to a +subscriber. How to build this notification is detailed in clause +5.11.7.

+

The supported JSON members shall follow the indications provided in +Table +5.3.2‑1.

+
+Table 5.3.2-1: CSourceNotification data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+CSource notification identifier (JSON-LD @id). +
+type +
+String +
+It shall be equal to "ContextSourceNotification" +
+1 +
+JSON-LD @type. +
+subscriptionId +
+String +
+Valid URI +
+1 +
+Identifier of the subscription that originated the notification. +
+notifiedAt +
+String +
+DateTime (see clause +4.6.3) +
+1 +
+Timestamp corresponding to the instant when the notification was +generated by the system. +
+data +
+CSource +
+
+Registration[] +
+ +
+1 +
+The content of the notification as NGSI-LD CSourceRegistrations. See clause +5.2.9. +
+triggerReason +
+String +
+TriggerReasonEnumeration (see clause +5.3.3) +
+1 +
+Indicates whether the CSources in the CSourceRegistration(s) in data are +newly matching (initial notification or creation), have been updated +(but still match) or do not match any longer. +
+

5.3.3 TriggerReasonEnumeration

+

The enumeration can take one of the following values:

+
    +
  • +"newlyMatching" - describes the case that the notified +Context Source Registration(s) newly +match(es) the identified subscription. This value is used in the first +notification and whenever a new Context +Source Registration matching the Subscription has been +registered, or an existing Context Source +Registration that did not match before has been updated in such a +way that it matches now. +
    • +
  • +"updated" - describes the case that the notified Context Source Registration that was part +of a previous notification has been updated, but still matches the +Subscription. +
    • +
  • +"noLongerMatching" - describes the case that the +notified Context Source Registration +that was part of a previous notification no longer matches the +Subscription, i.e. as a result of an update or because it was deleted. +
    • +
+

5.4 NGSI-LD +Fragments

+

When updating NGSI-LD elements (Entities, Attributes, Context Source Registrations or +Subscriptions) it is necessary to have a means of describing a set of +modifications to their content.

+

An NGSI-LD Fragment is a JSON Merge Patch document [16] and [i.10] which describes +changes to be made to a target JSON-LD document using a syntax that +closely mimics the document being modified.

+

An NGSI-LD Fragment is a JSON-LD Object which shall include the +following members:

+
    +
  • +id (optional for certain bindings where it can be determined from +the operation signature). It shall be equal to the id of the target +(mutated) NGSI-LD element. Attribute Fragments do not contain explicit +ids. +
    • +
  • +type (optional for certain bindings where it can be determined +from the operation signature). It shall contain the Type name(s) of the +target NGSI-LD element. +
    • +
  • +A member (following the same data representation and nesting structure) +for each new member to be added to the target NGSI-LD element. +
    • +
  • +A member (following the same data representation and nesting structure) +for each new member to be modified in the target NGSI-LD element, which +value shall correspond to the new member value to be given. +
    • +
+
+
+EXAMPLE 1: +
+
+The + +following + +Subscription + +Fragment + +allows + +the + +modification + +of + +a + +Subscription + +by + +changing + +its + +endpoint's + +URI: +
+
+
+
+{ +
+
+ "id": "urn:ngsi-ld:Subscription:MySubscription", +
+
+"type": "Subscription", +
+
+"endpoint": { +
+
+ "uri": "http://example.org/newNotificationEndPoint" +
+
+} +
+
+} +
+
+ +
+
+
    +
  • +A member (following the same data representation and nesting structure) +with value equal to an NGSI-LD Null shall cause for the member to be +removed from the target NGSI-LD element. +
    • +
+
+
+EXAMPLE 2: +
+
+The + +following + +NGSI-LD + +Fragment + +allows + +the + +modification + +of + +an + +Entity + +by + +changing + +its + +batteryLevel + +Attribute, + +updating + +the + +observedAt + +sub-Attribute, + +removing + +the + +providedBy + +sub-Attribute + +and + +removing + +the + +uncharged + +Attribute + +from + +the + +Entity: +
+
+
+
+{ +
+
+"id": "urn:ngsi-ld:TemperatureSensor:001", +
+
+"type": "TemperatureSensor", +
+
+"batteryLevel": { +
+
+"type": "Property", +
+
+"value": 7, +
+
+"observedAt": "2022-03-14T12:51:02.000Z", +
+
+"providedBy": "urn:ngsi-ld:null" +
+
+}, +
+
+"uncharged" : { +
+
+"type": "Property", +
+
+"value": "urn:ngsi-ld:null" +
+
+} +
+
+} +
+
+ +
+
+

5.5 Common +Behaviours

+

5.5.1 Introduction

+

This clause defines common behaviours for the API operations.

+

When comparing URIs, implementations shall follow the recommendations +of IETF RFC 3986 [5], +section 6.

+

5.5.2 Error types

+

Table +5.5.2‑1 details a list of error types defined by NGSI-LD. The +particular conditions under which error type shall be raised are defined +when describing each operation supported by the API.

+
+Table 5.5.2-1: Error types in NGSI-LD +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Error Type +
+Description +
+https://uri.etsi.org/ngsi-ld/errors/InvalidRequest +
+The request associated to the operation is syntactically invalid or +includes wrong content +
+https://uri.etsi.org/ngsi-ld/errors/BadRequestData +
+The request includes input data which does not meet the requirements of +the operation +
+https://uri.etsi.org/ngsi-ld/errors/AlreadyExists +
+The referred element already exists +
+https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported +
+The operation is not supported +
+https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound +
+The referred resource has not been found +
+https://uri.etsi.org/ngsi-ld/errors/InternalError +
+There has been an error during the operation execution +
+https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery +
+The query associated to the operation is too complex and cannot be +resolved +
+https://uri.etsi.org/ngsi-ld/errors/TooManyResults +
+The query associated to the operation is producing so many results that +can exhaust client or server resources. It should be made more +restrictive +
+https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable +
+A remote JSON-LD @context referenced in a request cannot be retrieved by +the NGSI-LD Broker and expansion or compaction cannot be performed +
+https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport +
+The NGSI-LD API implementation does not support multiple tenants +
+https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant +
+The addressed tenant does not exist +
+

5.5.3 Error +response payload body

+

When reporting errors back to clients, NGSI-LD implementations shall +generate a JSON object in accordance with IETF RFC 7807 [10], section 3.1, including, +at least the following terms:

+
    +
  • +type: Error type as per clause +5.5.2. +
    • +
  • +title: Error title which shall be a short string +summarizing the error. +
    • +
  • +detail: A detailed message that should convey enough +information about the error. +
    • +
+

Even though IETF RFC 7807 [10] defines a specific MIME +type for error payloads, NGSI-LD implementations shall use the standard +JSON MIME type ("application/json") when +reporting errors, so that old clients or existing tools are not +broken.

+
+
+EXAMPLE: +
+
+ +
+
+
+
+{ +
+
+"type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound", +
+
+"title": "Resource not found.", +
+
+"detail": "urn:ngsi-ld:Device:widget001 was not found", +
+
+"status": 404, +
+
+"instance": "urn:ngsi-ld:Device:widget001" +
+
+} +
+
+ +
+
+

5.5.4 General +NGSI-LD validation

+

All the operations that take a JSON-LD document as input shall +process such JSON-LD document as follows:

+
    +
  • +If the request payload body is not a valid JSON document then an error +of type InvalidRequest shall be raised. +
    • +
  • +If the data included by the JSON-LD document is not syntactically +correct, according to the @context or +the API data type definitions, then an error of type BadRequestData shall be raised. +
    • +
  • +A Context Producer may supply an additional hint regarding the overall +validity of the payload body and the version of the NGSI-LD +specification that the API datatype definitions conform to. When +receiving such an annotated context production request, a Context Broker +that it is only partially capable of interpreting the datatypes held +within the payload body may use this information to amend the data held +within the payload through applying fallbacks (see clause +4.3.6.8) prior to validation. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as +a first level member value ("<key>": +"urn:ngsi-ld:null"), with +the exception of NGSI-LD Fragments (see clause +5.4) used in partial update and merge operations (as mandated by clause +5.5.8 and clause +5.5.12) or to represent deleted Properties in concise representation +as part of notifications, shall result in an error of type +BadRequestData. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as the right-hand +side of value in a Property, as the right-hand side of +object in a Relationship or to use {"@none": "urn:ngsi-ld:null"} as the right-hand +side of languageMap, with the exception of NGSI-LD Fragments (see +clause +5.4) used in update and merge operations (as mandated by clause +5.5.8 and clause +5.5.12) and the representation of deleted Properties, Relationships +or Language Properties in notifications and the temporal evolution, +shall result in an error of type BadRequestData. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as the value of a key +value pair within a JSON object, which is the right-hand side of the +value of a Property, with the exception of NGSI-LD Fragments used +in merge operations (see clause +5.5.12), shall result in an error of type BadRequestData. +
    • +
+

5.5.5 Default +@context assignment

+

If the input provided by an API client does not include any +@context, then the implementation shall at minimum assign the +Core @context to such an input. In addition, the Context Broker implementation may allow +configuring a default user @context (with default terms), to be +used when no user @context is provided. The Core @context +shall always take precedence.

+

5.5.6 Operation +execution and generic error handling

+

When executing an operation if an unexpected error happens and the +operation cannot be completed, implementations shall raise an error of +type InternalError. This includes, as well, situations such as +database timeouts, etc.

+

If the NGSI-LD endpoint is not capable of executing the requested +operation, an error of type OperationNotSupported shall be +raised. This may happen in a distributed architecture where a Context Broker might not be able to store +Entities (only to forward queries to Context +Sources), and as a result, certain operations such as "Create +Entity" might not be supported.

+

When a query operation is so complex that cannot be resolved by an +NGSI-LD system, implementations shall raise an error of type +TooComplexQuery.

+

When a query operation is producing so many results that can +potentially exhaust client or server resources, or it can be just +impractical to be managed, implementations shall raise an error of type +TooManyResults. The threshold conditions used as criteria to +raise such error is up to each implementation.

+

When a remote JSON-LD @context referenced by an incoming +request is not available, implementations shall raise an error of type +LdContextNotAvailable. If the remote JSON-LD @context is +invalid, implementations shall raise an error of type +BadRequestData.

+

5.5.7 Term to URI expansion +or compaction

+

NGSI-LD API operations allow clients to use short-hand strings as +non-qualified names, particularly for Property, +Relationship or Type names and VocabProperty values. For instance, an API +client can refer to the term "Vehicle" as +a non-qualified type name. When executing API update-related operations, +NGSI-LD systems shall expand terms to URIs, in order to obtain and store +Fully Qualified Names. Likewise, when executing query-related +operations, NGSI-LD systems shall compact URIs (Fully Qualified Names) +to short terms in order to provide short-hand strings to context +consumers.

+

The term to URI expansion or compaction shall be performed using a +@context as described by the JSON-LD specification [2] (section 5.1), and in clause +4.4. In the absence of a user +@context, the term expansion or compaction shall be +performed according to clause +5.5.5.

+

For the avoidance of doubt, the @context used to perform +compaction or expansion of terms shall be the one provided by +each API call (or the default @context in its absence), +and not any other @context which might have been supplied +previously. For instance, when performing "Query Entity" operations (clause +5.7.2), the @context used to perform URI expansion and +compaction shall be the one provided by the request.

+

In case of HTTP binding via GET (clause 6.4.3.2) of the "Query +Entity" operation, this means using the JSON-LD Link Header as described +by the JSON-LD specification [2], section 6.2. In case of +HTTP binding via POST (clause 6.23.3.1), of the "Query Entity" +operation, this means giving the @context either via Link Header +or within the payload body, depending on the Content-Type Header being +"application/json" or "application/ld+json", respectively.

+

It is important to warn users that updating a @context could +lead to behaviour that might be perceived as inconsistent. If, for +instance, a fully qualified name that qualified a given short-hand name +is changed, from that moment onwards, the short-hand name is referencing +a different Attribute. This will effectively change the results of +queries that use the given short name, possibly not giving back anymore +the expected set of results.

+

Moreover, this user @context shall not:

+
    +
  • +Contain JSON-LD Scoped Contexts (see [2], section 4.1.8). +
    • +
  • +Be embedded into NGSI-LD Attributes, i.e. there cannot be parts of the +user @context other than at the top level of the NGSI-LD +document. +
    • +
+

Parts of user @context that are not following the two points +above should result in an error of type BadRequestData, because +JSON-LD Scoped Contexts and nested embedded @context could be +used to modify terms defined in the Core @context or to reshape NGSI-LD +Elements during the expansion of terms.

+

As the Core @context is protected and cannot be overridden, when +performing term to URI expansion or compaction, implementations +shall always consider the Core @context +as having absolute precedence, regardless of the +position of the Core @context in the @context array of +elements. Nonetheless, NGSI-LD data providers may use appropriate term +prefixing to ensure that a proper term to URI expansion or compaction is +performed.

+

At compaction time, in the event that no matching term is found in +the current @context, implementations shall render Fully +Qualified Names.

+
+
+EXAMPLE: +
+
+An + +entity + +of + +type + +"Vehicle" + +bound + +to + +a + +certain + +@context +, + +C, + +will + +match + +a + +query + +by + +"Vehicle" +type + +if + +and + +only + +if + +the + +supplied + +query + +@context +, + +Q, + +maps + +the + +term + +"Vehicle" + +to + +the + +same + +URI + +as + +C. +
+
+
+Note that the JsonProperty is designed to hold native JSON values +which are by definition not available for expansion and compaction via +an @context. Therefore the given short-hand name is always used +for accessing JSON keys within a JsonProperty json +element. +
+

5.5.8 Partial Update Patch +Behaviour

+

The Partial Update Patch procedure modifies an existing NGSI-LD +element by overwriting the data at the Attribute level, replacing it +with the data provided in the NGSI-LD Fragment.

+

When updating NGSI-LD elements (Entities, Context Source Registrations or Context +Subscriptions) using NGSI-LD Fragments, implementations shall determine +the exact set of changes being requested by comparing the content of the +provided Fragment (patch) against the current content (a JSON-LD object) +of the target element.

+

With respect to update operations, implementations shall perform an +algorithm equivalent to the one described below (adapted from IETF RFC +7396 [16]), in order +to observe the name to URI expansion rules and the JSON-LD null +processing):

+
    +
  • +For each member of the Fragment perform the term to URI expansion. +
    • +
  • +If the provided Fragment (a JSON Merge Patch document) contains members +that do not appear within the target (their URIs do not match), those +members are added to the target. +
    • +
  • +For each member of the Fragment contained by the target, the target +member value is replaced by the value given in the Fragment. In the case +of a member representing a reified Property or Relationship including a +datasetId, such member is only replaced if the datasetId +is the same, otherwise the member of the Fragment is added as a new +instance to the target. If no datasetId is present, the default +Attribute instance is targeted and replaced if present and otherwise +added. In case of a member type (of an entity) in Entity +Fragments, all included Entity Types are added, if they are not already +contained in the type member of the target. +
    • +
  • +For each member of the Fragment, whose value is an NGSI-LD Null, +contained by the target, the target member is deleted. In the case of +deleting a specific Attribute instance with a datasetId, the +handling shall be in accordance with the description found in clause +5.6.5. A datasetId cannot be deleted by setting it to the +value "urn:ngsi-ld:null". +
    • +
+
+
+EXAMPLE 1: +
+
+Given + +an + +Entity + +containing + +the + +following + +Property: +
+
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+ +
+
+
+
+ +
+
+ +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+
+EXAMPLE 2: +
+
+Given + +an + +Entity + +containing + +the + +following + +Property +: +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+
+EXAMPLE 3: +
+
+Given + +an + +Entity + +containing + +the + +following + +Property +: +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": +"urn:ngsi-ld:null" +
+
+} +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+

5.5.9 Pagination +Behaviour

+
+5.5.9.1 General Pagination Behaviour +
+

When resolving NGSI-LD Query operations, NGSI-LD Systems shall +exhibit the behaviour described by the present clause:

+
    +
  • +Let Md be equal to the default maximum number of +NGSI-LD Elements to be retrieved by the API during each query pagination +iteration, as defined by the NGSI-LD implementation. +
    • +
  • +Let Mc be equal to the maximum number of NGSI-LD +Elements to be retrieved as requested by the NGSI-LD Client. If +Mc is undefined then it shall be equal to +Md. +
    • +
  • +Let L be the maximum number of NGSI-LD Elements to be +retrieved by the API during each query pagination iteration. +L shall be equal to Mc. +
    • +
  • +During query execution and for each pagination iteration, the query +resolution mechanisms of the NGSI-LD System shall ensure that only up to +a maximum of L NGSI-LD Elements are retrieved and +returned to the NGSI-LD client, i.e. the maximum page size per iteration +shall not overpass L. Nonetheless, implementations +shall take care of not overpassing a maximum size of response payload +body, which, in practice, implies that, under certain circumstances, the +number of Elements retrieved per page can be lower than +L. +
    • +
  • +After the retrieval of each page (containing at most L NGSI-LD +Elements) implementations shall check whether there are pending +NGSI-LD Elements to be retrieved in the context of the current query. If +that is the case, implementations shall flag NGSI-LD Clients of the +existence of such NGSI-LD Elements. Ultimately, the flagging mechanisms +used shall depend on each API binding but shall be present as mandated +by the present clause. +
    • +
  • +When flagging the existence of additional NGSI-LD Elements (pages) +pending to be retrieved, generally, implementations shall provide +NGSI-LD Clients pointers to get access to both the following page of +NGSI-LD Elements and the previous one, according to the current +pagination iteration. +
    • +
  • +The pointer to the previous page of NGSI-LD Elements shall be included +for all pagination iterations excepting the first one, as, obviously, +there will be no previous NGSI-LD Elements. +
    • +
  • +When the last page of NGSI-LD Elements is reached, only the pointer to +the previous page shall be provided to NGSI-LD Clients, so that they can +detect that no more NGSI-LD Elements are available. +
    • +
  • +The pointers to NGSI-LD Elements shall contain all the parameters needed +to allow NGSI-LD Clients to retrieve the next and previous page, without +further interactions with the API. +
    • +
+

While iterating over a set of pages, there might be changes in the +target result set, due to additions or removals of NGSI-LD Elements +occurring in between. Implementations may detect those situations and +may warn NGSI-LD Clients appropriately. During pagination, the same +@context shall be used. An attempt to use a different @context should +result in an BadRequestData error.

+
+5.5.9.2 Pagination option using limit and offset +
+

The general pagination behaviour described in only requires pointers +to the following and previous pages, which can be implemented in a +completely opaque way. Pagination may also be implemented in a +transparent way, giving the Context Consumer more control over the +process. In this case, the parameters limit and offset +should be used, allowing the Context Consumer to adapt the size of the +page using limit and jump to a desired set of elements in the +results using offset.

+
+5.5.9.3 Pagination with Entity maps +
+

In the case of queries based on Entity maps, the set of Entities +considered for the result is fixed with the initial query creating the +Entity map. However, the Entity information itself can be dynamic, so +filters shall be rechecked before returning results. In the case of +split Entities, the Entities in the Entity map can only be considered as +candidate Entities, since, at the time of Entity map creation, the +Entities have not been aggregated and thus the filters could not be +applied. This can only be done when preparing a page for pagination. +Thus, Entities not or no longer fitting the query shall be removed from +the Entity map during pagination. Pages shall always be filled to the +maximum, as long as Entities are available. When using the previous +link, the set of Entities on the previous page may not be the same as +before, due to dynamic changes resulting in Entities no longer +fulfilling the filter criteria of the query. As a result, the first page +when going backward, and the last page, when going forward, may have +less than the maximum number of Entities.

+

5.5.10 Multi-Tenant Behaviour

+

If a Tenant is specified for an +NGSI-LD operation, the operation shall only be applied to information +related to the specified Tenant. If +no Tenant is specified, the operation +shall apply to the implicitly existing default Tenant. If a Tenant is explicitly specified, but the +system implementing the NGSI-LD API does not support multi-tenancy, an +error of type NoMultiTenantSupport should be raised.

+

In case an operation applies to a Tenant, this information shall also be +provided in the response to the operation. This also applies to +notifications sent as a result of subscriptions (clauses 5.8 +and 5.11).

+

A Tenant is represented in form of +a String. How the Tenant is specified +for an API operation is protocol binding specific. How Tenants +are created, is implementation-specific.

+

One implementation option is to support the implicit creation of +Tenants. This means that a Tenant is implicitly created when an +NGSI-LD operation for creating information targets a new Tenant; this is the case for:

+ +

All other NGSI-LD operations, e.g. for retrieving, updating, +appending or deleting information that target a non-existing Tenant should raise an error of type +NonexistentTenant.

+

If the system implementing the NGSI-LD API does not support multiple +Tenants, the attempt to register a Context Source with Tenant information in the Context Source Registration should also +result in an error of type NoMultiTenantSupport.

+

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

+

5.5.11.0 Foreword

+

The following operations operate on an array of entities (as input +payload):

+ +

It is allowed for such an input Entity array to contain more than one +instance of the same entity (those instances have identical ids).

+

In order for such a request to be correctly handled, those instances +that have the same id are processed by the Broker in the order +they have in the array: the higher the index in the array, the later it +will be processed. If the order is altered, the outcome may be +altered.

+

All Entities and Attributes in the batch will get the same +modifiedAt timestamp, so it makes sense to distinguish them via +the observedAt temporal property.

+

Implementations shall treat the entity instances as if they had all +arrived in separate requests.

+

The following clauses specify the behaviour in each case.

+

5.5.11.1 Batch Entity Creation +case

+

The first occurrence of an entity in the input array (the oldest one) +is used for the creation of the entity. Any subsequent instance of the +same entity is reported as an error (entity already exists) in the +response.

+

5.5.11.2 Batch Entity +Creation or Update (Upsert) case

+

This operation has two modes of operation, with an optional flag to +select between the two. The default behaviour is to replace any already +existing entities, while the optional behaviour is to update already +existing entities. Non existing entities are created in both modes.

+

If the entity does not yet exist, the first occurrence of an entity +is used to create the entity, and subsequent instances of that same +entity are used to either replace (default behaviour) or to update +(optional behaviour) the entity. These replace or update operations +shall be done in chronological order.

+

Only the entity resulting from merging all of the entity instances, +in the correct order, is maintained in the current state (as defined in +clause +4.3.1). For Temporal Evolution of +Entities (as defined in clause +4.3.1), all entity instances shall be taken into account, in the +correct order.

+

5.5.11.3 Batch Entity Update case

+

This operation has two modes of operation, with an optional flag to +select between the two. The default behaviour is to replace any already +existing attributes of the entities, while the optional behaviour is to +preserve already existing attributes of the entities.

+

Brokers shall send separate notifications for each individual update, +taking throttling into account.

+

5.5.11.4 Batch Entity Delete case

+

The Batch Entity Delete operation has as input an array of Entity +IDs, for the entities to be deleted. If an Entity ID is replicated in +the array, the first occurrence will delete the entity, while subsequent +occurrences of the same Entity ID will provoke an error in the response +(entity does not exist).

+

5.5.11.5 Batch Entity Merge case

+

The Batch Entity Merge operation has as input an array of Entity IDs, +for the entities to be merged. If an Entity ID is replicated in the +array, these merge operations shall be done in chronological +order. Only the entity resulting from merging all of the entity +instances, in the correct order, is maintained in the current state (as +defined in clause +4.3.1). For Temporal Evolution of +Entities (as defined in clause +4.3.1), all entity instances shall be taken into account, in the +correct order.

+

5.5.12 Merge +Patch Behaviour

+

The merge patch procedure modifies an existing NGSI-LD element by +applying the set of changes found in an NGSI-LD Fragment data to the +target resource. Unlike the partial update patch behaviour (described in +clause +5.5.8), which replaces the complete element on the first level, e.g. +a whole Attribute, the procedure described in this clause merges the +provided information with the existing information up to an arbitrary +depth, e.g. including going into JSON objects representing a Property +value.

+

When merging NGSI-LD Entities using NGSI-LD Fragments, +implementations shall determine the exact set of changes being requested +by comparing the content of the provided Fragment (patch) against the +current content (a JSON-LD object) of the target element.

+

With respect to merge operations, implementations shall perform an +algorithm equivalent to the one described below (adapted from IETF RFC +7396 [16], in order +to observe the name to URI expansion rules and JSON-LD null +processing):

+
    +
  • +For each member of the Fragment perform the term to URI expansion. +
    • +
  • +If the provided Fragment (a JSON Merge Patch document) contains members +that do not appear within the target (their URIs do not match), those +members are added to the target. +
    • +
  • +For each member of the Fragment contained by the target, the target +member value is merged with the value given in the +Fragment. NGSI-LD Nulls within the Fragment are given special meaning to +indicate the removal of existing values within the target member value. +In the case of a member representing a reified Property or Relationship +including a datasetId, such member is only updated if the +datasetId is the same, otherwise the member of the Fragment is +added as a new instance to the target. If no datasetId is +present, the default Attribute instance is targeted and merged if +present and otherwise added. In case of a member type (of an +Entity) in Entity Fragments, all included Entity Types are added, if +they are not already contained in the type member of the target. +
    • +
  • +For each member of the Fragment, whose value is an NGSI-LD Null, +contained by the target, the target member is removed. In the case of +deleting a specific Attribute instance with a datasetId, the +handling shall be according to the description in clause +5.6.5. A datasetId cannot be deleted by setting it to the +value "urn:ngsi-ld:null". +
    • +
+
+
+EXAMPLE 1: +
+
+Given + +an + +Entity + +containing + +the + +following + +Property +: +
+
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 25, +
+
+    "unitCode": "CEL" +
+
+    "observedAt": "2022-03-14T01:59:26.535Z" +
+
+  } +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 100, +
+
+    "observedAt": "2022-03-14T13:00:00.000Z" +
+
+  } +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 100, +
+
+    "unitCode": "CEL", +
+
+    "observedAt": "2022-03-14T13:00:00.000Z" +
+
+  } +
+
+} +
+
+ +
+
+
+EXAMPLE 2: +
+
+Given + +an + +Entity + +containing + +the + +following + +Property +: +
+
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value" : { +
+
+          "street": "Straße des 17. Juni", +
+
+          "city": "Berlin", +
+
+          "country": "Germany" +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value" : { +
+
+          "street": "Pariser Platz", +
+
+          "country": "urn:ngsi-ld:null" +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+
+ +
+
+ +
+
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value": { +
+
+          "street": "Pariser Platz", +
+
+          "city": "Berlin" +
+
+    } +
+
+} +
+

5.5.13 Limiting operations to +local scope

+

The API provides a binding-specific mechanism to limit the execution +of operations to a local scope, i.e. to only execute it based on +information available in the Context +Source or Context Broker +directly targeted by the request. This enables limiting cascading +distributed operations (clause +4.3.6.4) and, in some cases, also enables broader local operations, +e.g. pertaining to all entities, which would be too +expensive in the distributed case.

+

The localOnly member in the +Subscription (clause +5.5.12) requests that the subscription only matches Entities stored +locally.

+

The localOnly member in the +RegistrationManagementInfo (clause 5.2.34) of a Context Source Registration request that, +when contacting the registered Context +Source, a local scope shall be +specified. Thus, the registered Context +Source only provides its local information, not information from +further Context Sources in its own +Context Registry.

+

If the request limits the execution of the operation to the local +scope, Context Source Registrations +from the Context Registry are not +required and thus do not need to be requested.

+

5.5.14 Distributed +Transactional Behaviour

+

The following operations may occur as part of a distributed +transactional request:

+ +

In the case that a client wishes to indicate to a Context Broker that +a request is part of a unitary sequence of requests, the Context Broker +shall create and cache an EntityMap for future use and should return the +location of said EntityMap in a specific field. The caching strategy and +expiry time shall take into account a suggested expiry time, if present, +and depend on implementation specific configurations. Context Sources +should indicate that they do not support EntityMaps, through declining +to return the location of an EntityMap when requested to do so.

+

If a subsequent request references an existent EntityMap, it shall be +used for the purposes of Entity registration matching, and queries shall +be filtered to only consider the Entities listed. Subsequent requests +referencing an EntityMap shall use the same parameters as in the +original request that created the EntityMap, except for the +specification of Entity identifiers or parameters related to pagination, +or, in the case of temporal requests, the temporal query. If an +EntityMap has expired, or cannot be accessed, no inference can be made +as to which entities are held within the Context Sources and a new one +shall be created. An EntityMap fixes the Entities to be considered for +subsequent requests based on it. The creating Context Source shall +remove Entities from the EntityMap that do not match the filters of the +query at the time of processing. Other components shall only be allowed +to update the expiry timestamp of the EntityMap, which can optionally be +extended if the Context Sources implementation allows for it.

+

5.6 Context +Information Provision

+

5.6.1 Create Entity

+

5.6.1.1 Description

+

This operation allows creating a new NGSI-LD Entity.

+

5.6.1.2 Use case +diagram

+

A Context Producer can create an +Entity within an NGSI-LD system as shown in Figure +5.6.1.2‑1.

+
+ +
+
+Figure 5.6.1.2-1: Create entity use case +
+

5.6.1.3 Input data

+

A JSON-LD document representing an NGSI-LD Entity as mandated by clause +5.2.4.

+

5.6.1.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI), Attributes +from matching input data are forwarded for remote processing: +
    • +
+
    +
  • +For matching Registrations where the Create Entity operation is +supported, the operation is forwarded to the registration endpoint. If +the endpoint then raises an error, this shall result in an error in case +the complete create failed or in a partial success if some parts of the +create succeeded. +
    • +
  • +For matching Registrations where the Create Entity operation is not +supported, this shall result in an error of type Conflict if the +complete Create Entity operation failed or in a partial success if some +parts of it succeeded. +
    +
    +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints: +
    • +
+
    +
  • +For matching Registrations where the Create Entity operation is +supported, matching input data is forwarded. If any such endpoint then +raises an error, this shall result in an error in case the complete +create has failed or in a partial success if some parts of the create +has succeeded. +
    • +
  • +For matching redirect Registrations where the Create +Entity operation is not supported, this shall result in an error of type +Conflict if the complete Create Entity operation failed or in a +partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing by +matching endpoints in case the Create Entity operation is supported. +
    • +
  • +If the Entity already exists locally this shall result in an error of +type AlreadyExists, if the complete Create Entity operation has +failed or in a partial success if some parts of it has succeeded. +
    • +
  • +Any remaining input data shall be used to create the Entity locally. +
    • +
+

5.6.1.5 Output data

+

None.

+

5.6.2 Update +Attributes

+

5.6.2.1 Description

+

This operation allows modifying an existing NGSI-LD Entity by +updating already existing Attributes (Properties or +Relationships) and by appending non-existing ones.

+

5.6.2.2 Use case +diagram

+

A Context Producer can update +Attributes within an NGSI-LD system as shown in Figure +5.6.2.2‑1.

+
+ +
+
+Figure 5.6.2.2-1: Update Attributes use case +
+

5.6.2.3 Input data

+
    +
  • +A URI representing the id of the Entity to be updated (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
+

5.6.2.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent to the target entity held locally, and no matching +registrations apply (see ), an error of type ResourceNotFound +shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded for +remote processing. For each matching registration: +
    • +
+
    +
  • +If the Update Attributes operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Update Attributes operation is not supported by the registration, +this shall result in an error of type Conflict if the complete +update failed or in a partial success if some parts of the update +succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +If there are remaining Attributes, for any inclusive +Context Source Registrations that +exist and match against the remaining input data, that input data is +also forwarded for remote processing to matching endpoints in case the +Update Attributes operation is supported by the matched registration. +
    • +
  • +Then, implementations shall perform a partial update patch operation +over the remains of the target Entity as mandated by clause +5.5.8, using the following procedure. +
    • +
  • +For each Attribute (Property or Relationship) included by the Entity +Fragment at root level: +
    • +
+
    +
  • +If the target Entity does not include a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7) then such Attribute shall be appended to the target Entity. +
    • +
  • +If the target Entity already includes a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7): +
    • +
+
    +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
+- If an Attribute instance in the target Entity has the same +datasetId and the Attribute value is not NGSI-LD Null, then the +existing Attribute instance with the specified datasetId in the +target Entity shall be replaced by the new one supplied. +
+
+- If an Attribute instance in the target Entity has the same +datasetId and the Attribute value is NGSI-LD Null then the +existing Attribute instance with the specified datasetId in the +target Entity shall be deleted. +
+
+- Otherwise the Attribute instance with the specified datasetId +shall be appended to the target Entity. +
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment, the default Attribute instance is targeted: +
    • +
+
+- If the default Attribute instance is present and the Attribute value is +not NGSI-LD Null, then the existing Attribute in the target +Entity shall be replaced by the new one supplied. +
+
+- If the default Attribute instance is present and the Attribute value is +NGSI-LD Null, then the existing Attribute in the target Entity +shall be deleted. +
+
+- Otherwise the default Attribute instance shall be appended to the +target Entity. +
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and the target entity +includes scope, replace the scope by the one included in the +Fragment, otherwise ignore it. +
    • +
+

5.6.2.5 Output data

+
    +
  • +A status code indicating whether all the new Attributes were updated or +only some of them. +
    • +
  • +List of Attributes (Properties or Relationships) actually updated. +
    • +
+

5.6.3 Append +Attributes

+

5.6.3.1 Description

+

This operation allows modifying an NGSI-LD Entity by adding new +attributes (Properties or Relationships).

+

5.6.3.2 Use case +diagram

+

A Context Producer can append new +Attributes to an existing Entity within an NGSI-LD system as shown in Figure +5.6.3.2‑1.

+
+ +
+
+Figure 5.6.3.2-1: Append Attributes use case +
+

5.6.3.3 Input data

+
    +
  • +A URI representing the id of the E to be modified (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
  • +An optional flag indicating whether overwriting existing Attributes +within the append operation should be permitted or denied. By default, +Attribute overwrites are permitted. +
    • +
+

5.6.3.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about this Entity, because there +is no existing Entity which id (URI), and where specified type, is +equivalent held locally to the one passed as a parameter, and no +matching registrations apply (see ), an error of type +ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Append Attributes operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Append Attributes operation is not supported by the registration, +this shall result in an error of type Conflict if the complete +append failed or in a partial success if some parts of the append +succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing to +matching endpoints in case the Append Attributes operation is supported. +
    • +
  • +Then, implementations shall perform an Append Attributes operation over +the remains of the target Entity as using the following procedure: +
    • +
+
    +
  • +For each Attribute (Property or Relationship) included by the Entity +Fragment at root level: +
    • +
+
    +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
+- If no Attribute instance of the same target Entity exists that has the +same datasetId, then such an Attribute shall be appended to the +target Entity. +
+
+- If an Attribute instance of the same target Entity exists that has the +same datasetId: +
+
+
+- If overwrite is allowed, then the existing Attribute with the specified +datasetId in the target Entity shall be replaced by the new one +supplied. +
+
+- If overwrite is not allowed, the existing Attribute with the specified +datasetId in the target Entity shall be left untouched. +
+
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment: +
    • +
+
+- If no default Attribute instance of the same target Entity exists, then +such Attribute shall be appended to the target Entity. +
+
+- If a default Attribute instance of the same target Entity exists: +
+
+
+- If overwrite is allowed, then the existing default Attribute in the +target Entity shall be replaced by the new one supplied. +
+
+- If overwrite is not allowed the existing default Attribute in the +target Entity shall be left untouched. +
+
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and overwrite is allowed, +the scope of the target Entity will become the one included in the +Fragment. Otherwise, the Scopes in the Fragment that are not part of the +value of scope of the target Entity will be appended to the value +of the scope of the target Entity. If there is more than one +Scope, the value of scope is represented as a JSON array +containing all Scopes. +
    • +
+

5.6.3.5 Output data

+
    +
  • +A status code indicating whether all the new Attributes were appended or +only some of them. +
    • +
  • +List of Attributes (Properties and/or Relationships) actually appended. +
    • +
+

5.6.4 Partial +Attribute update

+

5.6.4.1 Description

+

This operation allows performing a partial update on an +NGSI-LD Entity's Attribute (Property or Relationship). A +partial update only changes the elements provided in an Entity Fragment, +leaving the rest as they are. This operation supports the deletion of +sub-Attributes but not the deletion of the whole Attribute itself.

+

5.6.4.2 Use case +diagram

+

A Context Producer can carry out a +partial Attribute update of an Entity within an NGSI-LD System as shown +in Figure +5.6.4.2‑1.

+
+ +
+
+Figure 5.6.4.2-1: Partial Attribute update use case +
+

5.6.4.3 Input data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be modified, identified +by a name. +
    • +
  • +A JSON-LD document representing an NGSI-LD Attribute Fragment. +
    • +
+

5.6.4.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not valid or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute is scope, then an error of type +BadRequestData shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Partial Attribute update operation is supported by the +registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Partial Attribute update operation is not supported by the +registration, this shall result in an error of type Conflict in +case the complete partial Attribute update failed, or in a partial +success if some parts of the partial Attribute update succeeded. +
    +
    +No further processing is required. +
    • +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints in case the Partial Attribute update operation is supported. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7, so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute: +
    • +
+
    +
  • +as a default instance in case no datasetId is present; +
    • +
  • +as an instance with the specified datasetId if present; +
    • +
+
+then an error of type ResourceNotFound shall be raised. +
+
    +
  • +Perform a partial update patch operation on the target Attribute +following the algorithm mandated by clause +5.5.8. If present in the provided NGSI-LD Entity Fragment, the type +of the Attribute has to be the same as the type of the targeted +Attribute fragment, i.e. it is not allowed to change the type of an +Attribute. +
    • +
+

5.6.4.5 Output data

+

None.

+

5.6.5 Delete +Attribute

+

5.6.5.1 Description

+

This operation allows deleting an NGSI-LD Attribute (Property or +Relationship). The Attribute itself and all its children shall be +deleted.

+

5.6.5.2 Use case +diagram

+

A Context Producer can delete a +specific Attribute within an NGSI-LD system as shown in Figure +5.6.5.2‑1.

+
+ +
+
+Figure 5.6.5.2-1: Delete Attribute use case +
+

5.6.5.3 Input data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +An optional parameter identifying the datasetId of the target +Attribute instance to be deleted. Otherwise the default Attribute +instance is targeted. +
    • +
  • +An optional flag deleteAll indicating whether also all target +Attribute instances with a datasetId are to be deleted. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.5.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data (see ), the input data is forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Delete Attribute operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Delete Attribute update operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete delete Attribute failed, or in a partial success if +some parts of the delete Attribute succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply, then an +error of type ResourceNotFound shall be raised. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints in case the Delete Attribute operation is supported by the +matched registration. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute then an error +of type ResourceNotFound shall be raised. +
    • +
  • +If the target Attribute is scope, remove the scope +Attribute from the target Entity. +
    • +
  • +If the deleteAll flag is set, remove all target Attribute +instances from the target Entity. +
    • +
  • +Otherwise: +
    • +
+
    +
  • +if a datasetId parameter is provided, remove only the target +Attribute instance from the given dataset whose datasetId matches +the parameter; +
    • +
  • +if no datasetId parameter is provided, remove the default target +Attribute instance from the target Entity. +
    • +
+

5.6.5.5 Output data

+

None.

+
+5.6.6 Delete Entity +
+

5.6.6.1 Description

+

This operation allows deleting an NGSI-LD Entity.

+

5.6.6.2 Use case +diagram

+

A Context Producer can completely +delete an Entity within an NGSI-LD system as shown in Figure +5.6.6.2‑1.

+
+ +
+
+Figure 5.6.6.2-1: Delete Entity use case +
+

5.6.6.3 Input data

+
    +
  • +Entity ID (URI) of the Entity to be deleted, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
+

5.6.6.4 Behaviour

+
    +
  • +If the target Entity ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or Context +Source Registration matches against the id, the request is +forwarded for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Delete Entity operation is supported by the registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Delete Entity update operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete delete Entity failed, or in a partial success if some +parts of the delete Entity succeeded. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints: +
    • +
+
    +
  • +For matching Registrations where the Delete Entity operation is +supported (see clause +4.3.6), matching input data is forwarded. If any such endpoint then +raises an error, the implementation shall return with the error(s) +raised. +
    • +
  • +For matching redirect Registrations where the Delete +Entity operation is not supported, this shall result in an error of type +Conflict in case the complete delete Entity failed, or in a +partial success if some parts of the delete Entity succeeded. +
    • +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Delete +Entity operation is supported for remote processing by matching +endpoints. +
    • +
  • +The input data shall be used to remove the entity locally if it exists. +
    • +
+

5.6.6.5 Output +data

+

None.

+

5.6.7 Batch Entity +Creation

+

5.6.7.1 Description

+

This operation allows creating a batch of NGSI-LD Entities.

+

5.6.7.2 Use case +diagram

+

A Context Producer can create a +batch of NGSI-LD Entities within an NGSI-LD system as shown in Figure +5.6.7.2‑1.

+
+ +
+
+Figure 5.6.7.2-1: Create a batch of Entities use case +
+

5.6.7.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an NGSI-LD Entity as mandated by clause 5.2.4. +See clause +5.5.11.1 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
+

5.6.7.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity successfully created. S shall be initialized to the empty +array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    • +
+
    +
  • +Let IN be a copy of the original input array. +
    • +
  • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
    • +
  • +If IN is empty, continue with the next Context Source Registration if there is +any. +
    • +
  • +If the Batch Entity Creation operation is supported by CSR: +
    • +
+
    +
  • +Forward the Batch Entity Creation request with IN as input Array. +
    • +
  • +Merge the returned list of Entities successfully created with S. +
    • +
  • +Merge the returned list of Entities in Error with E. +
    • +
+
    +
  • +Otherwise, if the Create Entity operation (clause +5.6.1) is supported by CSR: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward a Create Entity request for Entity EN. +
+
+- Merge any successful result(s) for Entity EN created with S. +
+
+- Merge any error result(s) for Entity EN created with E. +
+
    +
  • +Otherwise: +
    • +
+
    +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
+
    +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.1, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully created, then add the corresponding +Entity ID to the S array. +
    • +
  • +If the Entity creation failed, then a new BatchEntityError shall +be added to E containing the failed Entity ID and the related +ProblemDetails. +
    • +
+

5.6.7.5 Output data

+
    +
  • +The list of Entities successfully created (S Array), if all Entities +were created correctly; or +
    • +
  • +the list of Entities successfully created (S Array) and the list of +Entities in error (E Array), if only some or none of the Entities were +created. +
    • +
+

5.6.8 Batch Entity +Creation or Update (Upsert)

+

5.6.8.1 Description

+

This operation allows creating a batch of NGSI-LD Entities, updating +each of them if they already existed. In some database jargon this kind +of operation is known as "upsert".

+

5.6.8.2 Use case +diagram

+

A Context Producer can create or +update a batch of Entities within an NGSI-LD system as shown in Figure +5.6.8.2‑1.

+
+ +
+
+Figure 5.6.8.2-1: Upsert a batch of Entities use case +
+

5.6.8.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.2 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
  • +An optional flag indicating the update mode (only applies in case the +Entity already exists): +
    • +
+
    +
  • +Replace. All the existing Entity content shall be replaced (default +mode). +
    • +
  • +Update. Existing Entity content shall be updated. +
    • +
+

5.6.8.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +to the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    • +
+
    +
  • +Let IN be a copy of the original input array. +
    • +
  • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
    • +
  • +If IN is empty, continue with the next Context Source Registration if there is +any. +
    • +
  • +If the Batch Entity Creation or Update (Upsert) operation is supported +by CSR: +
    • +
+
    +
  • +Forward the Batch Entity Creation or Update (Upsert) request with IN as +input Array. +
    • +
  • +Merge the returned list of Entities successfully created with S. +
    • +
  • +Merge the returned list of Entities in Error with E. +
    • +
+
    +
  • +Otherwise, if the Create Entity operation (clause +5.6.1) is supported by CSR: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward a Create Entity request for Entity EN. +
+
+- If an error of type AlreadyExists is returned: +
+
+
+- If the Replace Entity operation (clause +5.6.18) is supported by CSR and the value of the update mode flag is +Replace or the flag is not set, forward a Replace Entity request +for Entity EN. +
+
+- Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and the value of the update mode flag is +Update, forward an Update Attributes request for Entity EN. +
+
+- Otherwise add an OperationNotSupported Error for Entity EN +related to CSR to E. +
+
+
    +
  • +Merge any successful result(s) for Entity EN created or updated with S. +
    • +
  • +Merge any error result(s) for Entity EN created or updated with E. +
    • +
+
    +
  • +Otherwise, if the Replace Entity operation (clause +5.6.18) is supported by CSR and the value of the update mode flag is +Replace or the flag is not set: +
    • +
+
    +
  • +Forward a Replace Entity request for Entity EN. +
    • +
  • +Merge any successful result(s) for Entity EN updated with S. +
    • +
  • +Merge any error result(s) for Entity EN updated with E. +
    • +
+
    +
  • +Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and the value of the update mode flag is +Update: +
    • +
+
    +
  • +Forward an Update Attributes request for Entity EN. +
    • +
  • +Merge any successful result(s) for Entity EN updated with S. +
    • +
  • +Merge any error result(s) for Entity EN updated with E. +
    • +
+
    +
  • +Otherwise: +
    • +
+
    +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
+
    +
  • +For each of the NGSI-LD Entities included in the input Array +implementations shall: +
    • +
+
    +
  • +Create the Entity locally if it does not exist (i.e. no Entity with the +same Entity ID is present) executing the behaviour defined by clause +5.6.1, but limited to a local operation. +
    • +
  • +If there were an existing Entity with the same Entity ID, it shall be +completely replaced by the new Entity content provided, if the requested +update mode is 'replace'. +
    • +
  • +If there were an existing Entity with the same Entity ID, the behaviour +defined by clause +5.6.3 shall be executed, but limited to a local operation, if the +requested update mode is "update". +
    • +
+
    +
  • +If successful, the local creation or update shall be added to S. If +while processing an Entity there is any kind of error or abnormal +situation, a BatchEntityError shall be added to E containing the +failed Entity ID and the related ProblemDetails. +
    • +
+

5.6.8.5 Output data

+
    +
  • +none (if all Entities already existed and are successfully updated); or +
    • +
  • +the list of Entities successfully created (S Array), if all Entities not +existing prior to this request have been successfully created and the +others have been successfully updated; or +
    • +
  • +the list of Entities successfully created or updated (S Array), and the +list of Entities in error (E Array), if only some or none of the +Entities have been successfully created or updated. +
    • +
+

5.6.9 Batch Entity +Update

+

5.6.9.1 Description

+

This operation allows updating a batch of NGSI-LD Entities.

+

5.6.9.2 Use case +diagram

+

A Context Producer can update a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.9.2‑1.

+
+ +
+
+Figure 5.6.9.2-1: Update a batch of Entities use case +
+

5.6.9.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.3 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
  • +An optional flag indicating whether Attributes shall be overwritten or +not. By default, Attributes will be overwritten. +
    • +
+

5.6.9.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +as the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized as the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    • +
+
    +
  • +Let IN be a copy of the original input array. +
    • +
  • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
    • +
  • +Remove all Entities without Attributes from IN. +
    • +
  • +If IN is empty, continue with the next Context Source Registration if there is +any. +
    • +
  • +If the Batch Entity Update operation is supported by CSR: +
    • +
+
    +
  • +Forward the Batch Entity Update request with IN as input Array. +
    • +
  • +Merge the returned list of Entities successfully created with S. +
    • +
  • +Merge the returned list of Entities in Error with E. +
    • +
+
    +
  • +Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and Attribute overwrite is permitted: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward an Update Attributes request for Entity EN. +
+
+- Merge any successful result(s) for Entity EN updated with S. +
+
+- Merge any error result(s) for Entity EN updated with E. +
+
    +
  • +Otherwise, if the Append Attributes operation (clause +5.6.3) is supported by CSR and Attribute overwrite is not permitted: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward an Append Attributes request for Entity EN with Attribute +overwrite disabled: +
+
+
+- Merge any successful result(s) for Entity EN updated with S. +
+
+- Merge any error result(s) for Entity EN updated with E. +
+
+
    +
  • +Otherwise: +
    • +
+
    +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
+
    +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.3, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully updated (Attributes appended), then add +the corresponding Entity ID to the S array. +
    • +
  • +If the Entity update failed, then a new BatchEntityError shall be +added to E containing the failed Entity ID and the ProblemDetails +associated. +
    • +
+

5.6.9.5 Output data

+
    +
  • +none (if all Entities are successfully updated); or +
    • +
  • +the list of Entities successfully updated (S Array), and the list of +Entities in error (E Array), if only some or none of the Entities have +been successfully updated. +
    • +
+

5.6.10 Batch Entity +Delete

+

5.6.10.1 Description

+

This operation allows deleting a batch of NGSI-LD Entities.

+

5.6.10.2 Use case +diagram

+

A Context Producer can delete a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.10.2‑1.

+
+ +
+
+Figure 5.6.10.2-1: Delete a batch of Entities use case +
+

5.6.10.3 Input data

+
    +
  • +A JSON-LD Array containing a list of Entity IDs (URIs) that are +requested to be deleted. See clause +5.5.11.4 for information on behaviour when there is more than one +instance of the same Entity ID in the input Array. +
    • +
+

5.6.10.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +to the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    • +
+
    +
  • +Let IN be a copy of the original input array. +
    • +
  • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
    • +
  • +Remove all Entities without Attributes from IN. +
    • +
  • +If IN is empty, continue with the next Context Source Registration if there is +any. +
    • +
  • +If the Batch Entity Delete operation is supported by CSR: +
    • +
+
    +
  • +Forward the Batch Entity Delete request with IN as input Array. +
    • +
  • +Merge the returned list of Entities successfully created with S. +
    • +
  • +Merge the returned list of Entities in Error with E. +
    • +
+
    +
  • +Otherwise, if the Delete Entity operation ) is supported by CSR: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward a Delete Entity request for Entity EN. +
+
+- Merge any successful result(s) for Entity EN deleted with S. +
+
+- Merge any error result(s) for Entity EN deleted with E. +
+
    +
  • +Otherwise: +
    • +
+
    +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
  • +For each of the NGSI-LD Entity IDs included in the input Array execute +the behaviour defined by , but limited to a local operation, as follows: +
    • +
+
+- If the Entity corresponding to an Entity ID was successfully deleted, +then add such Entity ID to the S array. +
+
+- If the Entity deletion failed, then a new BatchEntityError shall +be added to E containing the failed Entity ID and the related +ProblemDetails. +
+

5.6.10.5 Output +data

+
    +
  • +none (if all Entities that already existed are successfully deleted); or +
    • +
  • +the list of Entities successfully deleted (S Array), and the list of +Entities in error (E Array), if some or all of the Entities have not +been successfully deleted. +
    • +
+

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

+

5.6.11.1 Description

+

This operation allows creating or updating (by adding new Attribute +instances) the Temporal Evolution of an +Entity.

+

5.6.11.2 Use case +diagram

+

A Context Producer can create the +Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.11.2‑1.

+

Similarly, if the Entity already exists then an Update scenario will +be in place.

+
+ +
+
+Figure 5.6.11.2-1: Create or Update (Upsert) Temporal Evolution of an +Entity use case +
+

5.6.11.3 Input +data

+

A JSON-LD document representing the Temporal Evolution of an +Entity as mandated by clause +5.2.20.

+

5.6.11.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI), Attributes +from matching input data are forwarded for remote processing: +
    • +
+
    +
  • +For matching Registrations where the "Create or Update (Upsert) Temporal +Evolution of an Entity" operation is supported, the operation is +forwarded to the registration endpoint. If the endpoint then raises an +error, this shall result in an error in case the complete "Create or +Update (Upsert) Temporal Evolution of an Entity" operation failed or in +a partial success if some parts of it succeeded. +
    • +
  • +For matching Registrations where the "Create Entity" operation is not +supported, this shall result in an error of type Conflict in case +the complete "Create or Update (Upsert) Temporal Evolution of an Entity" +operation failed or in a partial success if some parts of it succeeded. +
    +
    +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints: +
    • +
+
    +
  • +For matching Registrations where the "Create or Update (Upsert) Temporal +Evolution of an Entity" operation is supported, matching input data is +forwarded. If any such endpoint then raises an error, this shall result +in an error in case the complete "Create or Update (Upsert) Temporal +Evolution of an Entity" operation failed or in a partial success if some +parts of it succeeded. +
    • +
  • +For matching redirect Registrations where the "Create +or Update (Upsert) Temporal Evolution of an Entity" operation is not +supported, this shall result in an error of type Conflict in case +the complete "Create or Update (Upsert) Temporal Evolution of an Entity" +operation failed or in a partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing by +matching endpoints. +
    • +
  • +If the NGSI-LD endpoint already knows about this Temporal Evolution of an +Entity, because there is an existing Temporal Evolution of an +Entity whose id (URI) is the same, then all the Attribute +instances included by the Temporal Evolution shall be added to the +existing Entity as mandated by clause +5.6.12. If type is included in the EntityTemporal Fragment +and it includes Entity Type names that are not yet in the target Temporal Evolution of an +Entity, add them to the list of Entity Type names of the target +Temporal Evolution of +anEntity. +
    • +
  • +Otherwise, implementations shall create the provided Temporal Evolution of an +Entity. +
    • +
+

5.6.11.5 Output +data

+

None.

+

5.6.12 Add +Attributes to Temporal Evolution of an Entity

+

5.6.12.1 Description

+

This operation allows modifying the Temporal Evolution of an +Entity by adding new Attribute instances.

+

5.6.12.2 Use case +diagram

+

A Context Producer can add new +Attributes or Attribute instances to an existing Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.12.2‑1.

+
+ +
+
+Figure 5.6.12.2-1: Add Attributes to Temporal Evolution of an Entity use +case +
+

5.6.12.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an +Entity to be modified with additional Attributes. +
    • +
  • +A JSON-LD document representing an NGSI-LD Fragment of +EntityTemporal, including only the new Attribute instance(s), and +contained by an Array. +
    • +
+

5.6.12.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Temporal Evolution of +an Entity, because there is no existing Temporal Evolution of an +Entity whose id (URI) is equivalent to the one passed as a +parameter held locally and no matching registrations apply, an error of +type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the "Add Attributes to Temporal Evolution of an Entity" operation is +supported by the matched registration, matching input data is forwarded +to the Registration endpoint. +
    • +
  • +If the "Add Attributes to Temporal Evolution of an Entity" operation is +not supported by the matched registration, this shall result in an error +of type Conflict if the complete "Add Attributes to Temporal +Evolution of an Entity" operation +failed or in a partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing to +matching endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally and +matches against the remaining input data, implementations shall do the +following: +
    • +
+
    +
  • +For each Attribute (Property or Relationship) instance included by the +EntityTemporal Fragment at root level: +
    • +
+
    +
  • +The Attribute (considering term expansion rules as mandated by clause +5.5.7) instance(s) shall be added to the target Temporal Evolution of an Entity. +
    • +
+
    +
  • +If type is included in the EntityTemporal Fragment and it +includes Entity Type names that are not yet in the target Temporal Evolution of an +Entity, add them to the list of Entity Type names of the target +Temporal Evolution of +theEntity. +
    • +
+

5.6.12.5 Output +data

+

None.

+

5.6.13 Delete +Attribute from Temporal Evolution of an Entity

+

5.6.13.1 Description

+

This operation allows deleting an Attribute (Property or +Relationship) of the Temporal Evolution of an +Entity. The Attribute itself and all its child NGSI-LD elements +shall be deleted.

+

5.6.13.2 Use case +diagram

+

A Context Producer can delete a +specific Attribute of the Temporal +Evolution of an Entity within an NGSI-LD system as +shown in Figure +5.6.13.2‑1.

+
+ +
+
+Figure 5.6.13.2-1: Delete Attribute from Temporal Evolution of an Entity +use case +
+

5.6.13.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be modified by removing the +target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +An optional parameter identifying the dataset (datasetId) of the +target Attribute instance to be deleted. +
    • +
  • +An optional parameter, a flag, (deleteAll) indicating whether all +target Attribute instances are to be deleted, regardless of +datasetId. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.13.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Temporal Evolution of an +Entity whose id (URI) is equivalent held locally and no matching +registrations apply, then an error of type ResourceNotFound shall +be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the "Delete Attribute from Temporal Evolution of an Entity" operation +is supported by the matched registration, matching input data is +forwarded to the Registration endpoint. +
    • +
  • +If the "Delete Attribute from Temporal Evolution of an Entity" operation +is not supported by the matched registration, this shall result in an +error of type Conflict in case the complete "Delete Attribute +from Temporal Evolution of an Entity" failed, or in a partial success if +some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
+
    +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Temporal Evolution of an +Entity does not contain the +target Attribute then an error of type ResourceNotFound shall be +raised. +
    • +
  • +If the deleteAll flag is set, remove all target Attribute +instances from the target Entity. +
    • +
+
    +
  • +Otherwise: +
    • +
+
    +
  • +if a datasetId parameter is provided, remove only any target +Attribute instance from the given dataset; +
    • +
  • +if no datasetId parameter is provided, remove only the default +target Attribute instance datasetId from the target Entity. +
    • +
+

5.6.13.5 Output +data

+

None.

+

5.6.14 Modify +Attribute instance in Temporal Evolution of an Entity

+

5.6.14.1 Description

+

This operation allows modifying a specific Attribute (Property or +Relationship) instance, identified by its instanceId, of the +Temporal Evolution of an +Entity.

+

This operation enables the correction of wrong information that could +have been previously added to the Temporal +Evolution of an Entity.

+

5.6.14.2 Use case +diagram

+

A Context Producer can modify a +specific Attribute instance, identified by a given instanceId, of +the Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.14.2‑1.

+
+ +
+
+Figure 5.6.14.2-1: Modify Attribute Instance in Temporal Evolution of an +Entity use case +
+

5.6.14.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be modified by changing an +instance of the target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be modified, identified +by a name. +
    • +
  • +Attribute instance to be modified, identified by its instanceId. +
    • +
  • +A JSON-LD document representing an NGSI-LD Fragment of +EntityTemporal, including only the new Attribute instance, +contained by an Array of exactly one item. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.14.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the target instanceId is not a valid URI or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the "Modify Attribute instance in Temporal Evolution of an Entity" +operation is supported by the matched registration, matching input data +is forwarded to the Registration endpoint. +
    • +
  • +If the "Modify Attribute instance in Temporal Evolution of an Entity" +operation is not supported by the matched registration, this shall +result in an error of type Conflict in case the complete Modify +Attribute instance in Temporal Evolution of an +Entity operation failed, or in a partial success if some parts of +it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
+
    +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Temporal Evolution of an +Entity does not contain the +target Attribute then an error of type ResourceNotFound shall be +raised. +
    • +
  • +If for the target Attribute no instance with the specified +instanceId exists, an error of type ResourceNotFound shall +be raised. +
    • +
+
    +
  • +Replace the target Attribute instance identified by the +instanceId with the Attribute instance in the +EntityTemporal Fragment. The createdAt property of the +concerned instance shall remain unchanged, but the modifiedAt +property shall be set to the timestamp corresponding to this +modification. +
    • +
+

5.6.14.5 Output +data

+

None.

+

5.6.15 Delete +Attribute instance from Temporal Evolution of an Entity

+

5.6.15.1 Description

+

This operation allows deleting one Attribute instance (Property or +Relationship), identified by its instanceId, of the Temporal Evolution of an +Entity. The Attribute itself and all its child elements shall be +deleted. This operation enables the removal of individual Attribute +instances that could have been previously added to the Temporal Evolution of an +Entity.

+

5.6.15.2 Use case +diagram

+

A Context Producer can delete an +Attribute instance, identified by a given instanceId, of the +Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.15.2‑1.

+
+ +
+
+Figure 5.6.15.2-1: Delete Attribute Instance from Temporal +Evolution
+of an Entity use case +
+

5.6.15.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolutionof an Entity to be modified by deleting an +instance of the target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +Attribute instance to be deleted, identified by its instanceId. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.15.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the target instanceId is not a valid URI or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the "Delete Attribute instance from Temporal Evolution of an Entity" +operation is supported by the matched registration, matching input data +is forwarded to the Registration endpoint. +
    • +
  • +If the "Delete Attribute instance from Temporal Evolution of an Entity" +operation is not supported by the matched registration, this shall +result in an error of type Conflict in case the complete "Delete +Attribute instance from Temporal Evolution of an Entity" failed, or in a +partial success if some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
+
    +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
+
    +
  • +If the target Temporal Evolution of +the Entity does not contain the target Attribute then an error of +type ResourceNotFound shall be raised. +
    • +
  • +If for the target Attribute no instance with the specified +instanceId exists, an error of type ResourceNotFound shall +be raised. +
    • +
  • +Remove the instance, with the specified instanceId, of the target +Attribute from the target Entity. +
    • +
+

5.6.15.5 Output +data

+

None.

+

5.6.16 Delete Temporal +Evolution of an Entity

+

5.6.16.1 Description

+

This operation allows deleting the Temporal Evolution of an +Entity.

+

5.6.16.2 Use case +diagram

+

A Context Producer can completely +delete the Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.16.2‑1.

+
+ +
+
+Figure 5.6.16.2-1: Delete Temporal Evolution of an Entity use case +
+

5.6.16.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be deleted. +
    • +
+

5.6.16.4 Behaviour

+
    +
  • +If the target Entity ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the "Delete Temporal Evolution of Entity" operation is supported by +the matched registration, matching input data is forwarded to the +Registration endpoint. +
    • +
  • +If the "Delete Temporal Evolution of Entity" operation is not supported +by the matched registration, this shall result in an error of type +Conflict in case the complete "Delete Temporal Evolution of +Entity" failed, or in a partial success if some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, the +entire Temporal Evolution of +the Entity shall be removed. +
    • +
+

5.6.16.5 Output +data

+

None.

+

5.6.17 Merge Entity

+

5.6.17.1 Description

+

This operation allows modification of an existing NGSI-LD Entity +aligning to the JSON Merge Patch processing rules defined in IETF RFC +7396 [16] by adding +new Attributes (Properties or Relationships) or modifying or deleting +existing Attributes associated with an existing Entity.

+

5.6.17.2 Use case +diagram

+

A Context Producer can perform a +merge on an Entity within an NGSI-LD system as shown in Figure +5.6.17.2‑1.

+
+ +
+
+Figure 5.6.17.2-1: Merge Entity use case +
+

5.6.17.3 Input +data

+
    +
  • +A URI representing the id of the Entity to be merged (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
  • +An optional flag indicating whether the JSON-LD document contains a +simplified representation of the entity. +
    • +
  • +An optional parameter indicating a common observedAt timestamp to +use across merged Attributes. +
    • +
  • +An optional parameter representing a common IETF RFC 5646 [28] language tag to use +across merged LanguageMap Attributes. +
    • +
+

5.6.17.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Merge Entity operation is supported by the matched registration +(see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Merge Entity operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete Merge Entity operation failed, or in a partial success +if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Merge +Entity operation is supported for remote processing to matching +endpoints. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
+
+ Then, implementations shall perform a merge operation over the target +Entity as mandated by clause +5.5.12, using the following procedure: +
+
+ For each Attribute (Property or Relationship) included by the Entity +Fragment: +
+
    +
  • +If the target Entity does not include a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7), then such Attribute shall be appended to the target Entity. +
    • +
  • +If the target Entity already includes a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7): +
    • +
+
    +
  • +If the Attribute (Property or Relationship) to be merged is represented +in a simplified representation, the type of any pre-existing +Attribute in the target entity shall be preserved. +
    • +
  • +If a common language tag is defined and a LanguageProperty +Attribute to be merged is represented as a string, the pre-existing +languageMap JSON object shall be preserved. The string value +shall only replace the value associated to the language tag key found +within the languageMap. +
    • +
  • +If a common observedAt timestamp is defined and an existing +Attribute to be merged previously contained an observedAt +sub-Attribute, the observedAt sub-Attribute is also updated using +the common timestamp, unless the Entity Fragment itself contains an +explicit updated value for the observedAt sub-Attribute. +
    • +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
+- If an Attribute instance in the target Entity has the same +datasetId: +
+
+- If overwrite is allowed and the Attribute value is not NGSI-LD Null, +then the existing Attribute with the specified datasetId in the +target Entity shall be merged with the new one supplied. +
+
+- If overwrite is allowed and the Attribute value is NGSI-LD Null, then +the existing Attribute with the specified datasetId in the target +Entity shall be deleted. +
+
+- If overwrite is not allowed, the existing Attribute with the specified +datasetId in the target Entity shall be left untouched. +
+
+- Otherwise the Attribute instance with the specified datasetId +shall be appended to the target Entity. +
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment, the default Attribute instance is targeted: +
    • +
+
+- If the default Attribute instance is present: +
+
+- If overwrite is allowed and the Attribute value is not NGSI-LD Null, +then the existing Attribute in the target Entity shall be merged with +the new one supplied. +
+
+- If overwrite is allowed and the Attribute value is NGSI-LD Null, then +the existing Attribute with the specified datasetId in the target +Entity shall be deleted. +
+
+- If overwrite is not allowed, the existing Attribute in the target +Entity shall be left untouched. +
+
+- Otherwise if value is not NGSI-LD Null, the default Attribute instance +shall be appended to the target Entity. +
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and overwrite is allowed, +the scope of the target Entity will become the one included in the +Fragment. Otherwise, the Scopes in the Fragment that are not part of the +value of scope of the target Entity will be appended to the value +of the scope of the target Entity. If there is more than one +Scope, the value of scope is represented as a JSON array +containing all Scopes. +
    • +
+

5.6.17.5 Output +data

+
    +
  • +A status code indicating whether all the Attributes were merged +successfully. +
    • +
  • +List of Attributes (Properties and/or Relationships) actually merged. +
    • +
+

5.6.18 Replace +Entity

+

5.6.18.1 Description

+

This operation allows the modification of an existing NGSI-LD Entity +by replacing all of the Attributes (Properties or Relationships).

+

5.6.18.2 Use case +diagram

+

A Context Producer can replace an +entire Entity within an NGSI-LD system as shown in Figure +5.6.18.2‑1.

+
+ +
+
+Figure 5.6.18.2-1: Replace Entity use case +
+

5.6.18.3 Input +data

+
    +
  • +A URI representing the id of the Entity to be replaced (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity. +
    • +
+

5.6.18.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls are not supported by this +operation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Replace Entity operation is supported by the registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Replace Entity operation is not supported by the registration, +this shall result in an error of type Conflict in case the +complete Replace Entity operation failed, or in a partial success if +some parts of it succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Replace +Entity operation is supported for remote processing to matching +endpoints. +
    • +
  • +If the target Entity exists locally, completely replace the existing +Entity with the same Entity ID with the new Entity content provided. The +system generated createdAt Temporal Property of the Entity as +defined in clause +4.8 remain unchanged. +
    • +
+

5.6.18.5 Output +data

+

None.

+

5.6.19 Replace +Attribute

+

5.6.19.1 Description

+

This operation allows the replacement of a single Attribute (Property +or Relationship) within an NGSI-LD Entity.

+

5.6.19.2 Use case +diagram

+

A Context Producer can carry out a +replacement of an Attribute within an Entity within an NGSI-LD System as +shown in Figure +5.6.19.2‑1.

+
+ +
+
+Figure 5.6.19.2-1: Replace Attribute use case +
+

5.6.19.3 Input +data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be replaced, identified +by a name. +
    • +
  • +A JSON-LD document representing an NGSI-LD Attribute Fragment. +
    • +
+

5.6.19.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not valid, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the target Attribute is scope, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the Replace Attribute operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Replace Attribute operation is not supported by the registration, +this shall result in an error of type Conflict in case the +complete Replace Attribute operation failed, or in a partial success if +some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Replace +Attribute operation is supported for remote processing to matching +endpoints. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7, so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute: +
    • +
+
    +
  • +as a default instance in case no datasetId is present; +
    • +
  • +as an instance with the specified datasetId if present; +
    • +
  • +then this shall result in an error of type ResourceNotFound in +case the complete Replace Attribute operation failed, or in a partial +success if some parts of it succeeded. +
    • +
+
    +
  • +Completely replace the existing Attribute with the new Attribute content +provided. The system generated createdAt Temporal Property as +defined in clause +4.8 remains unchanged. +
    • +
+

5.6.19.5 Output +data

+

None.

+

5.6.20 Batch Entity +Merge

+

5.6.20.1 Description

+

This operation allows modification of a batch of NGSI-LD Entities +according to the JSON Merge Patch processing rules defined in IETF RFC +7396 [16] by adding +new attributes (Properties or Relationships) or modifying or deleting +existing attributes associated with an existing Entity.

+

5.6.20.2 Use case +diagram

+

A Context Producer can merge a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.20.2‑1.

+
+ +
+
+Figure 5.6.20.2-1: Merge a batch of Entities use case +
+

5.6.20.3 Input +data

+

A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.5 for information on behaviour when there is more than one +instance of the same entity in the input Array.

+

5.6.20.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +as the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized as the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    • +
+
    +
  • +Let IN be a copy of the original input array. +
    • +
  • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
    • +
  • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
    • +
  • +Remove all Entities without Attributes from IN. +
    • +
  • +If IN is empty, continue with the next Context Source Registration if there is +any. +
    • +
  • +If the Batch Entity Merge operation is supported by CSR: +
    • +
+
    +
  • +Forward the Batch Entity Merge request with IN as input Array. +
    • +
  • +Merge the returned list of Entities successfully created with S. +
    • +
  • +Merge the returned list of Entities in Error with E. +
    • +
+
    +
  • +Otherwise, if the Merge Entity operation (clause +5.6.17) is supported by CSR: +
    • +
+
    +
  • +For each Entity EN in the input array: +
    • +
+
+- Forward a Merge Entity request for Entity EN. +
+
+- Merge any successful result(s) for Entity EN merged with S. +
+
+- Merge any error result(s) for Entity EN merged with E. +
+
    +
  • +Otherwise: +
    • +
+
    +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
+
    +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.17, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully merged (Attributes updated, appended or +deleted), then add the corresponding Entity ID to the S array. +
    • +
  • +If the Entity merge failed, then a new BatchEntityError shall be +added to E containing the failed Entity ID and the ProblemDetails +associated. +
    • +
+

5.6.20.5 Output +data

+
    +
  • +none (if all Entities already existed and are successfully merged); or +
    • +
  • +the list of Entities successfully merged (S Array), and the list of +Entities in error (E Array), if only some or none of the Entities have +been successfully merged. +
    • +
+

5.6.21 Purge Entities

+

5.6.21.1 Description

+

This operation allows the deletion of entities within an NGSI-LD +system based upon a query.

+

5.6.21.2 Use case +diagram

+

A Context Producer can delete a set of entities which matches a +specific query from an NGSI-LD system as shown in Figure +5.6.21.2‑1.

+
+ +
+
+Figure 5.6.21.2-1: Purge Entities use case +
+

5.6.21.3 Input data

+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type names (short hand string) and fully qualified type names (URI) +are allowed in the selector. +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A restrictive list of Attribute names to be deleted as attributes +(optional). +
    • +
  • +An exclusionary list Attribute names to be kept as attributes +(optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context +Sources by the values of properties that describe them) as per clause +4.9 (optional). +
    • +
+

In the general case, it is not possible to purge a set of entities by +only specifying desired Entity identifiers, without further specifying +restrictions on the entities' types or attributes, either explicitly, +via selector of Entity types or of Attribute names, or implicitly, +within an NGSI-LD Query or GeoQuery. If the execution of the operation +is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided.

+

5.6.21.4 Behaviour

+
    +
  • +At least one of the following input data shall be provided: +
    • +
+
+
+a) selector of Entity Types; +
+
+b) +list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause 5.5.13). +
+
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked +Entity retrieval, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the filter conditions specified by the query includes Linked Entity +attributes then an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
    • +
  • +Otherwise, implementations shall run a Query Entities operation (clause +5.6.2) to retrieve a list of ids of Entities for deletion, that meet +all of the following conditions (given the respective parameter is +provided): +
    • +
+
    +
  • +

  • [{[--B2plus--]}] id is equal to any of the id(s) passed as a +parameter; [{[--B2plus--]}]

    • +
  • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
    • +
  • +Attribute matches any of the expanded attribute(s) in the list that is +passed as a parameter; +
    • +
  • +id matches the id pattern passed as a parameter; +
    • +
  • +the filter conditions specified by the query are met (as mandated by clause +4.9); +
    • +
  • +the geospatial restrictions imposed by the geoquery are met (as mandated +by clause +4.10); if there are multiple instances of the GeoProperty on +which the geoquery is based, it is sufficient if any of these instances +meets the geospatial restrictions; +
    • +
  • +if the Scope query is present, it shall match a present Entity Scope (as +mandated by clause +4.19, for an example see annex +C, clause +C.5.15). +
    +
    +And thereafter: +
    • +
  • +when no restrictive list of Entity member names is present, the +implementation shall delete all Entities that can be found locally using +retrieved list of Entity ids; +
    • +
  • +when a restrictive list of Entity member names is present, the +implementation shall delete the given set of Attributes with those +member names from all Entities that can be found locally using retrieved +list of Entity ids; +
    • +
  • +when an exclusionary list of Entity member names is present, the +implementation shall delete all but the given set of Attributes with +those member names from all Entities that can be found locally using +retrieved list of Entity ids. +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source Registrations that match the query and +support the “purgeEntity” operation (see operations and operation groups +in clause +4.20), implementations shall do the following: +
    • +
  • +If an inclusive, exclusive or +redirect Context Source Registration matches against +the filter conditions specified, the request is forwarded for remote +processing. For each matching registration: +
    • +
+
    +
  • +If the Purge Entity operation is supported by the registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Purge Entity operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete purge Entities failed, or in a partial success if some +parts of purge Entities succeeded. +
    • +
+

5.6.21.5 Output data

+

None.

+

5.7 Context Information +Consumption

+

5.7.1 Retrieve +Entity

+

5.7.1.1 Description

+

This operation allows retrieving an NGSI-LD Entity.

+

5.7.1.2 Use case +diagram

+

A Context Consumer can retrieve a specific Entity from an +NGSI-LD system as shown in Figure +5.7.1.2‑1.

+
+ +
+
+Figure 5.7.1.2-1: Retrieve Entity use case +
+

5.7.1.3 Input data

+
    +
  • +Entity ID (URI) of the Entity to be retrieved (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +List of Attribute (Properties or Relationships) names to +be retrieved (projection attributes) (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be retrieved (projection attributes as defined by +clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +A language filter as defined by clause +4.15 (optional). +
    • +
  • +An optional JSON-LD context. +
    • +
  • +In the case of a GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +An optional flag indicating whether to include additional Linked Entities corresponding to the +Relationships retrieved and how to format those Linked Entities. See clause +4.5.23 (optional). +
    • +
  • +A limit to the depth of Linked +Entities to search whilst traversing an Entity graph. See clause +4.5.23 (optional). +
    • +
  • +A list (one or more) of Linked Entity identifiers previously encountered +whilst traversing an Entity graph. See clause +4.5.23 (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (optional). +
    • +
  • +A suggested lifetime for the EntityMap, if EntityMap is to be created +(optional). +
    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies +which Attribute instances are to be selected as defined by clause +4.5.5 (optional). +
    • +
+

5.7.1.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If geometryProperty parameter is present and the Accept Header is not +set to "application/geo+json", then an +error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval and the use of +Linked Entity retrieval is not +specified, or the projected attribute depth exceeds the Linked Entity retrieval depth, an error of +type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity held locally whose id (URI), and where +specified type, is equivalent, and no matching registrations apply, then +an error of type ResourceNotFound shall be raised. +
    • +
  • +The implementation shall retrieve any Attribute data held locally which +is associated with the Entity defined by the Entity ID. +
    • +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    • +
+
    +
  • +If the resource cannot be found, or the data has expired, a new +EntityMap shall be created. +
    • +
  • +If the data has not expired, only the retrieved Entity +Map shall be used to determine which Context +Source Registrations match the Entity ID. +
    • +
+
    +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +For Context Source Registrations that +match the Entity ID and support the retrieveEntity operation (see +operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If an EntityMap is in use for this operation, and an EntityMap entry +linked to a Context Source +Registration is found, the location of the linked EntityMap shall +be passed as part of any forwarded request. +
    • +
  • +For any exclusive, redirect and +inclusive Context Source +Registrations, the request is forwarded for remote retrieval by +matching endpoints, and remote Attribute data for the Entity is +received. If an expiresAt DateTime is present on the Entity and +the date lies in the past, the Attribute data shall be discarded, +otherwise the Attribute data is then merged together according to the +algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations the remote Attribute data received is added +to the payload only when an Attribute is not present in any of the +Attribute data received elsewhere. +
    • +
  • +If an EntityMap is in use for this operation, the EntityMap's linked +maps are updated to hold the location of every EntityMap used by the +Context Source Registrations. +
    • +
+
    +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +For each Attribute found in the target Entity, when the datasetId parameter is provided in the +request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId parameter, i.e. keep only the +Attribute instances whose datasetId +is specified. The default Attribute instance is matched, if "@none" is specified. +
    • +
  • +If there is no Attribute instance whose datasetId matches the value of the +parameter, the Attribute shall not be returned with the Entity. +
    • +
+
    +
  • +If the optional Attribute list is present and the NGSI-LD endpoint does +know about a matching Entity for the Entity ID, but this Entity does not +have any of the Attributes in the Attribute list, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If the Accept Header is set to "application/json" or "application/ld+json", return a JSON-LD object +representing the Entity as mandated by clause 5.2.4 +and containing only the Attributes requested (if present). +
    • +
+
    +
  • +If the Prefer Header [26] is set to +"ngsi-ld=<version>" then the ContextBroker shall endeavour to +amend the JSON-LD object to conform to the specified version of the +NGSI-LD specification as mandated in clause +4.3.6.8, and return a Preference-Applied Header set to +"ngsi-ld=<conformant-version>" in the response. +
    • +
+
    +
  • +If the Accept Header is set to "application/geo+json", a GeoJSON +Feature object representing the entity as mandated by clause 5.2.29 +and containing only the Attributes requested (if present): +
    • +
+
    +
  • +If the Prefer Header is omitted or set to "body=ld+json" then the Feature object +will also contain an @context field. +
    • +
  • +If the Prefer Header is set to "body=json" the @context is set as a +Link Header and removed from the Feature object. +
    • +
+

5.7.1.5 Output +data

+

A JSON-LD object representing the target Entity as mandated by clause 5.2.4 or +a GeoJSON Feature as mandated by clause +5.2.29.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be +compacted according to the supplied @context.

+

If a language filter is specified and any of the returned Attributes +corresponds to a LanguageProperty, the LanguageProperty in +question shall be converted into a Property. The value of this +Property shall correspond to the value of the string or strings +from the matching key-value pair of the languageMap where the key +matches the language filter. A non-reified subproperty lang shall +be included in the response indicating the chosen language.

+

If no match can be made for a LanguageProperty then a single +language shall be chosen, up to the implementation.

+

If inline Linked +Entity retrieval (see clause +4.5.23.2) is specified, and any of the returned Attributes +corresponds to an annotated Relationship, then unless a URI has +been previously encountered, an entity sub-Property shall be +included in the response holding the Linked +Entity data for each URI corresponding to that +Relationship's target object URI. If any of the returned +Attributes corresponds to an annotated ListRelationship, then an +entityList subproperty shall be included in the response holding +the ordered array of Linked +Entities corresponding to that ListRelationship's target +objectList URIs unless a URI has been previously encountered.

+

If flattened Linked +Entity retrieval (see clause +4.5.23.3) is specified, the response shall be an array of JSON-LD +objects representing the target entity itself and the targets of its +Relationships. If any of the returned Attributes corresponds to +an annotated Relationship, unless a target URI has been +previously encountered, the +data corresponding to each URI of the Relationship's target +object URIs is appended to the array. If any of the returned +Attributes corresponds to an annotated ListRelationship, then an +ordered array of additional Linked Entities is appended to the array +which hold the data corresponding to each of the URIs found within +ListRelationship's target objectList unless a URI has been +previously encountered.

+
+Flattened Linked Entity retrieval +output changes to a GeoJSON FeatureCollection as mandated by clause +5.2.30 if the Accept Header is set to "application/geo+json". +
+

If the location of a previously generated EntityMap was passed into +the request, or a flag to return an EntityMap was present in the +request, the location of the EntityMap used in the operation shall be +returned in a specific field in the response.

+

5.7.2 Query Entities

+

5.7.2.1 Description

+

This operation allows querying an NGSI-LD system.

+

5.7.2.2 Use case +diagram

+

A Context Consumer can retrieve a set of entities which +matches a specific query from an NGSI-LD system as shown in Figure +5.7.2.2‑1.

+
+ +
+
+Figure 5.7.2.2-1: Query Entities use case +
+

5.7.2.3 Input data

+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type names (short hand string) and fully qualified type names (URI) +are allowed in the selector. +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be retrieved (projection attributes as defined by +clause +4.21) (optional). +
    • +
  • +An exclusionary list member names ("id", +"type", "scope" or an +Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +In the case of GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties +that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9. +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +An optional flag indicating whether to include additional Linked Entities corresponding to the +Relationships retrieved and how to format those Linked Entities. See clause +4.5.23 (optional). +
    • +
  • +A limit to the depth of Linked +Entities to search whilst traversing an Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A list (one or more) of Linked Entity identifiers previously encountered +whilst traversing an Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (optional). +
    • +
  • +A suggested lifetime for the EntityMap, if EntityMap is to be created +(optional). +
    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies which Attribute instances are to be +selected as defined by clause +4.5.5 (optional). +
    • +
  • +A flag indicating whether split Entities are to be expected, i.e. +Entities whose information is distributed across different Context +Sources (optional). +
    • +
+

In the general case, it is not possible to retrieve a set of entities +by only specifying desired Entity identifiers, without further +specifying restrictions on the entities' types or attributes, either +explicitly, via selector of Entity types or of Attribute names, or +implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the +operation is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided.

+

5.7.2.4 Behaviour

+
    +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause +5.5.13). +
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval, and the use of +Linked Entity retrieval is not +specified, or the projected attribute depth exceeds the Linked Entity retrieval depth, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the filter conditions specified by the query includes Linked Entity attributes, and the use of +Linked Entity retrieval is not +specified, or the Linked Entity +attribute query depth exceeds the Linked Entity retrieval depth, an error of +type BadRequestData shall be raised (too deep query). +
    • +
  • +If geometryProperty parameter is present and the Accept Header is not +set to "application/geo+json", then an +error of type BadRequestData shall be raised. +
    • +
  • +Otherwise, +
    • +
+
    +
  • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
    • +
  • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
    • +
+
    +
  • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, and +local scope is not specified, implementations shall run a query that +shall return an Entity Array containing all the Entities found locally, +that meet all of the following conditions (given the respective +parameter is provided): +
    • +
+
    +
  • +id is equal to any of the id(s) passed as a parameter; +
    • +
  • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
    • +
  • +id matches the id pattern passed as a parameter. +
    • +
+
    +
  • +otherwise, implementations shall run a query that shall return an Entity +Array containing all the Entities found locally, that meet +all of the following conditions (given the respective +parameter is provided): +
    • +
+
    +
  • +id is equal to any of the id(s) passed as a parameter; +
    • +
  • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
    • +
  • +Attribute matches any of the expanded attribute(s) in the list that is +passed as a parameter; +
    • +
  • +id matches the id pattern passed as a parameter; +
    • +
  • +the filter conditions specified by the query are met (as mandated by clause +4.9); +
    • +
  • +the geospatial restrictions imposed by the geoquery are met (as mandated +by clause +4.10); if there are multiple instances of the GeoProperty on +which the geoquery is based, it is sufficient if any of these instances +meets the geospatial restrictions; +
    • +
  • +if the Scope query is present, it shall match a present Entity Scope (as +mandated by clause +4.19, for an example see annex +C, clause +C.5.15); +
    • +
  • +if the Attribute list is present, in order for an Entity to match, it +shall contain at least one of the Attributes in the projection Attribute +list. +
    • +
+
    +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    • +
+
    +
  • +If the resource cannot be found, or the data has expired, a new +EntityMap shall be created. +
    • +
  • +If the data has not expired, only the retrieved +EntityMap shall be used to determine which Context Source Registrations match the +Entity ID. +
    • +
+
    +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source +Registrations that match the query and support the "queryEntity" +operation (see operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If an EntityMap is in use for this operation, and an EntityMap entry +linked to a Context Source +Registration is found, the location of the EntityMap shall be +passed as part of the forwarded request. +
    • +
  • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, the +filters (filter conditions specified by the query, geospatial +restrictions imposed by the geoquery, Scope query, Attributes) shall be +removed before forwarding the request. These filters then have to be +applied after the Entity information from different Context Sources and +local information, if there is any, has been aggregated. +
    • +
  • +For any exclusive, redirect and +inclusive Context Source +Registrations, the request is forwarded for remote querying by +matching endpoints. The result of each remote query is an Entity Array. +Within each Entity Array, any Entities where an +expiresAt DateTime is present and the date lies in the past shall +be discarded. The Entity Arrays are then merged together with the +locally queried result according to the algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations, the request is forwarded for remote +querying by matching endpoints. Data from the Entity Array received is +added to the payload only when an Attribute is not already present in +the merged Entity Arrays are received elsewhere. +
    • +
+
    +
  • +If split Entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split Entities, and +local scope is not specified, the following filters shall be applied on +the aggregated Entities: +
    • +
+
    +
  • +the filter conditions specified by the query are met (as mandated by clause +4.9); +
    • +
  • +the geospatial restrictions imposed by the geoquery are met (as mandated +by clause +4.10); if there are multiple instances of the GeoProperty on +which the geoquery is based, it is sufficient if any of these instances +meets the geospatial restrictions; +
    • +
  • +if the Scope query is present, it shall match a present Entity Scope (as +mandated by clause +4.19, for an example see annex +C, clause +C.5.15); +
    • +
  • +if the Attribute list is present, in order for an Entity to match, it +shall contain at least one of the Attributes in the projection Attribute +list. +
    • +
+
    +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +

  • If in the process of obtaining the query result it is necessary +to issue a Context Source discovery +operation, the same Context Source +filter input parameter (if present) shall be propagated.

    • +
  • +For each Attribute found in the target Entity, when datasetId parameter is provided in the +request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId parameter, i.e. keep only the +Attribute instances whose datasetId +is specified. The default Attribute instance is matched, if "@none" is specified. +
    • +
  • +If there is no Attribute instance whose datasetId matches the value of the +parameter, the Attribute shall not be returned with the Entity. +
    • +
+
    +
  • +If the Accept Header is set to "application/json" or "application/ld+json", a JSON-LD +array is returned, representing the Entities as mandated by clause 5.2.4 +and containing only the Attributes requested (if present). +
    • +
+
    +
  • +If the Prefer Header [26] is set to +"ngsi-ld=<version>" then the ContextBroker shall endeavour to +amend the elements of the JSON-LD array to conform to the specified +version of the NGSI-LD specification as mandated in clause +4.3.6.8, and return a Preference-Applied Header set to +"ngsi-ld=<conformant-version>" in the response. +
    • +
+
    +
  • +If the Accept Header is set to "application/geo+json", the response shall be a +GeoJSON FeatureCollection as mandated by clause +5.2.30, with each Feature within the FeatureCollection +containing only the Attributes requested (if present): +
    • +
+
    +
  • +If the Prefer Header is omitted or set to "body=ld+json" then the +FeatureCollection will also contain an @context field. +
    • +
  • +If the Prefer Header is set to "body=json" the @context is sent +as a Link Header and removed from the FeatureCollection object. +
    • +
+

5.7.2.5 Output +data

+

A JSON-LD array representing the matching entities as defined by clause 5.2.4 or +in the case of GeoJSON requests a FeatureCollection as mandated +by clause +5.2.30. For each matching Entity, only the Attributes specified by +the Attribute list parameter shall be included. If such parameter is not +present, then all Attributes shall be included.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be +compacted according to the supplied @context.

+

If a language filter is specified and any of the returned Attributes +corresponds to a LanguageProperty, the LanguageProperty in +question shall be converted into a Property. The value of this +Property shall correspond to the value of the string or strings +from matching key-value pair of the languageMap where the key +matches the language filter. A non-reified subproperty lang shall be included in the +response indicating the chosen language.

+

If no match can be made for a LanguageProperty, then the +default identified by the JSON-LD "@none" shall be +chosen if present, otherwise the choice of a single language is up to +the implementation.

+

If inline Linked +Entity retrieval (see clause +4.5.23.2) is specified, and any of the returned Attributes +corresponds to an annotated Relationship, then unless a URI has +been previously encountered, an entity subproperty shall also be +included in the response holding the data for each URI corresponding to +that Relationship's target object URIs. If any of the +returned Attributes corresponds to an annotated ListRelationship, +then an entityList subproperty shall also be included in the +response holding the ordered data corresponding to that +ListRelationship's target objectList URIs, unless a URI +has been previously encountered.

+

If flattened Linked +Entity retrieval (see clause +4.5.23.3) is specified, the response shall be an array of JSON-LD +objects representing the matching entities and the targets of their +Relationships. If any of the returned Attributes corresponds to +an annotated Relationship, unless a URI has been previously +encountered, then data for each URI corresponding to the +Relationship's target object URIs is appended to the +array. If any of the returned Attributes corresponds to an annotated +ListRelationship, then an array of additional Linked Entities is appended to the array +which hold the data corresponding to each of the URIs found within +ListRelationship's target objectList unless a URI has been +previously encountered.

+

If the location of a previously generated EntityMap was passed into +the request, or a flag to return an EntityMap was present in the +request, the location of the EntityMap used in the operation shall be +returned in a specific field in the response.

+

5.7.3 Retrieve Temporal +Evolution of an Entity

+

5.7.3.1 Description

+

This operation allows retrieving the Temporal +Evolution of an Entity.

+

5.7.3.2 Use case +diagram

+

A Context Consumer can retrieve +the Temporal Evolution of an +Entity (in the form of a temporal representation) from an NGSI-LD +system as shown in Figure +5.7.3.2‑1.

+
+ +
+
+Figure 5.7.3.2-1: Retrieve Temporal Evolution of an Entity use case +
+

5.7.3.3 Input data

+
    +
  • +Entity ID (URI) of the target Temporal Evolutionof an +Entity to be retrieved. +
    • +
  • +List of Attribute (Properties or Relationships) names to be retrieved +(projection attributes) (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be retrieved (projection attributes as defined by +clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An NGSI-LD temporal query as mandated by clause +4.11 (optional). +
    • +
  • +A parameter (lastN) conveying that only the last N instances (per +Attribute) within the concerned temporal interval shall be retrieved +(optional). +
    • +
  • +An optional JSON-LD context. +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (optional). +
    • +

  • A suggested lifetime for the EntityMap, if EntityMap is to be +created (optional).

    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies +which Attribute instances are to be selected as defined by clause +4.5.5 (optional). +
    • +
+

5.7.3.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval, an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally, +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +The lastN parameter refers to a number, n, of Attribute +instances which shall correspond to the last n timestamps (in +descending ordering) of the temporal property (by default +observedAt) within the concerned temporal interval. +
    • +
  • +Let S be the Temporal Evolution of +the Entity as mandated by clause +5.2.20 with the specified Entity ID as it is available locally. S is +empty in case no Temporal Evolution of +the Entity is available locally. +
    • +
  • +From S, select only those Attribute instances (corresponding to the +Attributes specified by the query or all if none are specified) match +the temporal restrictions imposed by the temporal query (as mandated by +clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S1 be this new subset. +
    • +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    +
      +
    • +If the resource cannot be found, or the data has expired, a new +EntityMap shall be created. +
      • +
    • +If the data has not expired, only the retrieved Entity +Map shall be used to determine which Context Source Registrations match +the Entity ID. +
      • +
    • +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +For Context Source Registrations that +match the Entity ID and support the "retrieveTemporal" operation (see +operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If an EntityMap is in use for this operation, and an EntityMap entry +linked to a Context Source Registration is found, the location of the +linked EntityMap shall be passed as part of any forwarded request. +
    • +
  • +For any exclusive, redirect and +inclusive Context +Source, the request is forwarded for remote retrieval by matching +endpoints. and remote Attribute data for the Entity is received. The +result is then merged together with S1 according to the algorithm +defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations the remote Attribute data received is added +to S1 only when the Attribute instance, whose value of the +timeproperty, which is used for the temporal query +(observedAt as default), is not present in any of the Attribute +instances received from elsewhere. +
    • +
  • +If an EntityMap is in use for this operation, the EntityMap's linked +maps are updated to hold the location of every EntityMap used by the +Context Source Registrations. +
    • +
+
    +
  • +For the set of Attribute Instances +that are in S1, when datasetId +parameter is provided in the request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId parameter, i.e. keep only the +Attribute instances whose datasetId +is specified. The default Attribute instance is matched, if "@none" is specified. +
    • +
  • +If there is no Attribute instance whose datasetId matches the value of the +parameter, remove the complete Attribute from S1. +
    • +
+
    +
  • +From the set of Attribute Instances +that are in S1, include in their temporal representation only the +Attribute instances (up to lastN) corresponding to the query's +projection Attributes, or aggregated values of Attribute instances (if +aggregated temporal representation is requested). +
    • +
+

In the general case, it is not possible to retrieve a set of entities +by only specifying desired Entity identifiers, without further +specifying restrictions on the entities' types or attributes, either +explicitly, via selector of Entity types or of Attribute names, or +implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the +operation is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided.

+

5.7.3.5 Output +data

+

A JSON-LD object representing the Temporal Evolution of +the target Entity as mandated by clause +5.2.20.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

5.7.4 Query Temporal +Evolution of Entities

+

5.7.4.1 Description

+

This operation allows querying the Temporal +Evolution of Entities present in an NGSI-LD +system. It is similar to the operation defined by clause +5.7.2 (Query Entities) with the addition of a temporal query.

+

5.7.4.2 Use case +diagram

+

A Context Consumer can retrieve +the Temporal Evolution of a set of Entities which matches a specific +query from an NGSI-LD system as shown in Figure +5.7.4.2‑1.

+
+ +
+
+Figure 5.7.4.2-1: Query Temporal Evolution of Entities use case +
+

5.7.4.3 Input data

+
    +
  • +An NGSI-LD temporal query as mandated by clause +4.11. +
    • +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type name (short hand string) and fully qualified type name (URI) +are allowed. +
    • +
  • +A restrictive list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be retrieved (projection attributes as defined by +clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", +"scope" or +an Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties +that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9. +
    • +
  • +A parameter (lastN) conveying that only the last N instances (per +Attribute) within the concerned temporal interval shall be retrieved +(optional). +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (optional). +
    • +

  • A suggested lifetime for the EntityMap, if EntityMap is to be +created (optional).

    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies +which Attribute instances are to be selected as defined by clause +4.5.5 (optional). +
    • +

  • A flag indicating whether split Entities are to be expected, i.e. +Entities whose information is distributed across different Context +Sources (optional).

    +
    +In the general case, it is not possible to retrieve a set of entities by +only specifying desired Entity identifiers, without further specifying +restrictions on the entities' types or attributes, either explicitly, +via selector of Entity types or of Attribute names, or implicitly, +within an NGSI-LD query or geoquery. If the execution of the operation +is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided. +
    • +
+

5.7.4.4 Behaviour

+
    +
  • +If a temporal query is not provided then an error of type +BadRequestData shall be raised. +
    • +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause +5.5.13). +
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If projection attributes or filter conditions indicate the use of Linked Entity retrieval, an error of type +BadRequestData shall be raised. +
    • +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be observed +mandated by clause +5.5.7. +
    • +
  • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
    • +
  • +The lastN parameter refers to a number, n, of Attribute +instances which shall correspond to the last n timestamps (in +descending ordering) of the temporal property (by default +observedAt) within the concerned temporal interval. +
    • +
  • +Otherwise, +
    • +
+
    +
  • +Let S be the set of selected Entities i.e. the query result set. +
    • +
  • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, and +local scope is not specified, implementations shall run a query that +shall return an Entity Array containing all the Entities found locally, +that meet all of the following conditions (given the respective +parameter is provided): +
    +
      +

    • If id(s) is provided, keep in S only those Entities whose id is +equivalent to any of the id(s) passed as a parameter.

      • +

    • If an id pattern is provided, keep in S only those Entities whose +id matches the id pattern.

      • +

    • If a selector of Entity Types is provided, keep in S only those +Entities whose Entity Type names match the selector of Entity +Types.

      • +

    • From S, select only those Entities any of whose Attribute +instances (corresponding to the Attributes specified by the query or all +if none are specified) match the temporal restrictions imposed by the +temporal query (as mandated by clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S4 be this new subset.

      • +
    • +
  • +Implementations shall run a query that shall return the Temporal +Evolution of the matching Entities (all Entities stored locally, in case +only a local scope is specified); the logical steps to select the final +result set of Entities, and the Attribute instances included as part of +their temporal representation, are enumerated as follows: +
    +
      +

    • If id(s) is provided, keep in S only those Entities whose id is +equivalent to any of the id(s) passed as a parameter.

      • +

    • If an id pattern is provided, keep in S only those Entities whose +id matches the id pattern.

      • +

    • If a selector of Entity Types is provided, keep in S only those +Entities whose Entity Type names match the selector of Entity +Types.

      • +

    • From S, select only those Entities any of whose Attribute +instances (corresponding to the Attributes specified by the query or all +if none are specified) match the temporal restrictions imposed by the +temporal query (as mandated by clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S1 be this new subset.

      • +

    • If a values filter query is provided, from S1, select those +Entities whose Attribute instances (during the interval defined by the +temporal query) meet the matching conditions specified by the query (as +mandated by clause +4.9); i.e. the values filter query shall be checked against all the +Attribute instances resulting from the initial filtering performed by +the temporal query. Let S2 be this new subset.

      • +

    • If no values filter query is provided, then S2 is equal to +S1.

      • +

    • If geoquery is present, from S2, select those Entities whose +GeoProperty instances meet the geospatial restrictions imposed by +the geoquery (as mandated by clause +4.10); those geospatial restrictions shall be checked against the +GeoProperty instances that are within the interval defined by the +temporal query. Let S3 be this new subset.

      • +

    • If no geoquery is provided, then S3 is equal to S2.

      • +

    • If the Scope query is present, from S3, select those Entities +whose Entity Scope instances match the Scope query (as mandated by clause +4.19, for an example see annex +C, clause +C.5.16). Let S4 be the new subset.

      • +

    • If no Scope query is provided, then S4 is equal to S3.

      • +
    • +
+
    +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    +
      +

    • If the resource cannot be found, or the data has expired, a new +EntityMap shall be created.

      • +

    • If the data has not expired, only the retrieved EntityMap shall +be used to determine which Context Source Registrations match the Entity +ID.

      • +
    • +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source +Registrations that match the query and support the +"queryTemporal" operation (see operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If an EntityMap is in use for this operation, and an EntityMap entry +linked to a Context Source Registration is found, the location of the +EntityMap shall be passed as part of the forwarded request. +
    +
      +

    • If split entities flag is explicitly set to true or, if not +explicitly set, the default setting of the deployment allows split +entities, the filters (filter conditions specified by the query, +geospatial restrictions imposed by the geoquery, Scope query, +Attributes) shall be removed before forwarding the request. These +filters then have to be applied after the Entity information from +different Context Sources and local information, if there is any, has +been aggregated.

      • +
    • +
  • +For any exclusive, redirect and +inclusive Context Source +Registrations that match against the query, the request is +forwarded for remote querying by matching endpoints. The result of each +remote query is an Entity Array. The returned result is then merged into +S4 according to the algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations that match against the query, the request is +forwarded for remote querying by matching endpoints. Data from the +Entity Array received is merged only into S4 when an Attribute instance, +whose value of the timeproperty used for the temporal query, is not +already present in S4. +
    • +
+
    +
  • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, and +local scope is not specified, the following filters have to be applied +on the aggregated Entities: +
    • +
+
    +

  • If a values filter query is provided, from S4, select those +Entities whose Attribute instances (during the interval defined by the +temporal query) meet the matching conditions specified by the query (as +mandated by clause +4.9); i.e. the values filter query shall be checked against all the +Attribute instances resulting from the initial filtering performed by +the temporal query. Let S5 be this new subset.

    • +

  • If no values filter query is provided, then S5 is equal to +S4.

    • +

  • If geoquery is present, from S5, select those Entities whose +GeoProperty instances meet the geospatial restrictions imposed by the +geoquery (as mandated by clause +4.10); those geospatial restrictions shall be checked against the +GeoProperty instances that are within the interval defined by the +temporal query. Let S6 be this new subset.

    • +

  • If no geoquery is provided, then S6 is equal to S5.

    • +

  • If the Scope query is present, from S6, select those Entities +whose Entity Scope instances match the Scope query (as mandated by clause +4.19, for an example see annex +C, clause +C.5.16). Let S7 be the new subset.

    • +

  • If no Scope query is provided, then S7 is equal to S6.

    • +
+
    +
  • +Otherwise S7 is equal to S4 +
    • +
  • +If a datasetId parameter is provided, from S7, for all Entities, +filter the Attribute instances based on the datasetIds specified +in the parameter, i.e. keep only the Attribute instances +whosedatasetId is specified. The default Attribute instance is +matched, if "@none" is specified. Remove +all Attributes without remaining Attribute instances. Let S8 be this new +subset. +
    • +
  • +If no datasetId is provided then S8 equals to S7. +
    • +
  • +From the set of Entities that are in S8, include in their temporal +representation only the Attribute instances (up to lastN) +corresponding to the query's projection Attributes, or aggregated values +of Attribute instances (if aggregated temporal representation is +requested), and which meet the temporal, query and geoquery +restrictions. +
    +
    +If an aggregated temporal representation is requested and any of the +requested Attributes is not eligible for at least one of the aggregation +methods specified in the request parameters, then an error of type +InvalidRequest shall be raised. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
  • +If in the process of obtaining the query result it is necessary to issue +a Context Source discovery operation, +the same Context Source filter input +parameter (if present) shall be propagated. +
    • +
+

5.7.4.5 Output +Data

+

A JSON-LD array representing the matching entities as defined by clause +5.2.21 and selected according to the behaviour described by clause +5.7.4.4.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

5.7.5 Retrieve Available Entity +Types

+

5.7.5.1 Description

+

This operation allows retrieving a list of NGSI-LD entity types for +which entity instances exist within the NGSI-LD system.

+

5.7.5.2 Use case +diagram

+

A Context Consumer can retrieve a list of NGSI-LD entity types +from the system as shown in Figure +5.7.5.2‑1.

+
+ +
+
+Figure 5.7.5.2-1: Retrieve Available Entity Types use case +
+

5.7.5.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.5.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the list of entity types, as +mandated by clause +5.2.24, for which entity instances exist within the NGSI-LD system. +See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.5.5 Output +data

+

A JSON-LD object representing the list of available entity types, as +mandated by clause +5.2.24.

+

5.7.6 Retrieve Details +of Available Entity Types

+

5.7.6.1 Description

+

This operation allows retrieving a list with a detailed +representation of NGSI-LD entity types for which entity instances exist +within the NGSI-LD system. The detailed representation includes the type +name (as short name if available in the provided @context) and +the attribute names that existing instances of this entity type +have.

+

5.7.6.2 Use case +diagram

+

A Context Consumer can retrieve a list with a detailed +representation of NGSI-LD entity types from the system as shown in Figure +5.7.6.2‑1.

+
+ +
+
+Figure 5.7.6.2-1: Retrieve Details of Available Entity Types use case +
+

5.7.6.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.6.4 Behaviour

+
    +
  • +Return a list of JSON-LD objects representing the details of available +entity types as mandated by clause +5.2.25 for which entity instances exist within the NGSI-LD system. +See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.6.5 Output +data

+

A list of JSON-LD objects representing the details of available +entity types as mandated by clause +5.2.25.

+

5.7.7 Retrieve +Available Entity Type Information

+

5.7.7.1 Description

+

This operation allows retrieving detailed entity type information +about a specified NGSI-LD entity type for which entity instances exist +within the NGSI-LD system. The detailed representation includes the type +name (as short name if available in the provided @context), the +count of available entity instances and details about attributes that +existing instances of this entity type have, including their name (as +short name if available in the provided @context) and a list of +types the attribute can have (e.g. Property, Relationship +or GeoProperty).

+

5.7.7.2 Use case +diagram

+

A Context Consumer can retrieve a detailed representation of a +specified NGSI-LD entity type from the system as shown in Figure +5.7.7.2‑1.

+
+ +
+
+Figure 5.7.7.2-1: Retrieve Available Entity Type Information use case +
+

5.7.7.3 Input data

+
    +
  • +Entity type name for which detailed information is to be retrieved. +
    • +
  • +An optional JSON-LD context. +
    • +
+

5.7.7.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the details of the specified entity +type as mandated by clause +5.2.26, for which instances exist within the NGSI-LD system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.7.5 Output +data

+

A JSON-LD object representing the details of the specified entity +type as mandated by clause +5.2.26.

+

5.7.8 Retrieve Available +Attributes

+

5.7.8.1 Description

+

This operation allows retrieving a list of NGSI-LD attributes that +belong to entity instances existing within the NGSI-LD system.

+

5.7.8.2 Use case +diagram

+

A Context Consumer can retrieve a list of NGSI-LD attributes +from the system as shown in Figure +5.7.8.2‑1.

+
+ +
+
+Figure 5.7.8.2-1: Retrieve Available Attributes use case +
+

5.7.8.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.8.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the list of attributes as mandated +by clause +5.2.27 that belong to entity instances existing within the NGSI-LD +system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.8.5 Output +data

+

A JSON-LD object representing the list of available attributes as +mandated by clause +5.2.27.

+

5.7.9 Retrieve Details +of Available Attributes

+

5.7.9.1 Description

+

This operation allows retrieving a list with a detailed +representation of NGSI-LD attributes that belong to entity instances +existing within the NGSI-LD system. The detailed representation includes +the attribute name (as short name if available in the provided +@context) and the type names for which entity instances exist +that have the respective attribute.

+

5.7.9.2 Use case +diagram

+

A context consumer can retrieve a list with a detailed representation +of NGSI-LD attributes from the system as shown in Figure +5.7.9.2‑1.

+
+ +
+
+Figure 5.7.9.2-1: Retrieve Details of Available Attributes use case +
+

5.7.9.3 Input data

+

An optional JSON-LD context.

+

5.7.9.4 Behaviour

+

Return a list of JSON-LD objects representing the details of +available attributes as mandated by clause +5.2.28 (restricted to the elements id, type, +attributeName and typeNames) that belong to entity +instances existing within the NGSI-LD system. See clause +5.7.11 for architecture-related implementation aspects.

+

5.7.9.5 Output +data

+

A list of JSON-LD objects representing the details of available +attributes as mandated by clause +5.2.28 (restricted to the elements id, type, attributeName and +typeNames).

+

5.7.10 Retrieve +Available Attribute Information

+

5.7.10.1 Description

+

This operation allows retrieving detailed attribute information about +a specified NGSI-LD attribute that belongs to entity instances existing +within the NGSI-LD system. The detailed representation includes the +attribute name (as short name if available in the provided +@context) and the type names for which entity instances exist +that have the respective attribute, a count of available attribute +instances and a list of types the attribute can have (e.g. +Property, Relationship or GeoProperty).

+

5.7.10.2 Use case +diagram

+

A context consumer can retrieve a list with a detailed representation +of NGSI-LD attributes from the system as shown in Figure +5.7.10.2‑1.

+
+ +
+
+Figure 5.7.10.2-1: Retrieve Available Attribute Information use case +
+

5.7.10.3 Input +data

+
    +
  • +Name of the attribute for which detailed information is to be retrieved. +
    • +
  • +An optional JSON-LD context. +
    • +
+

5.7.10.4 Behaviour

+

Return a JSON-LD object representing the details of available +attributes as mandated by clause +5.2.28 that belong to entity instances existing within the NGSI-LD +system. See clause +5.7.11 for architecture-related implementation aspects.

+

5.7.10.5 Output +data

+

A JSON-LD object representing the details of available attributes as +mandated by clause +5.2.28.

+

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

+

Retrieving information about available types or attributes can be an +expensive operation depending on the scale and architectural design +decisions of the NGSI-LD system. This is in particular the case for +retrieving the information about all available entity types and +attributes related to all entity information available in an NGSI-LD +system. Especially in the case of distributed architecture (clause +4.3.3) and federated architecture (clause +4.3.4) checking all entities can be so expensive that it can become +practically infeasible.

+

Therefore, implementations may only take into account only +information that is available or can be derived from a local datastore +and the Context Registry, when +implementing the retrieval of available entity types and attributes, as +described in clauses 5.7.5, +5.7.6, +5.7.7, +5.7.8, +5.7.9 +and 5.7.10. +Context registrations do not always reflect which entity instances are +actually available from a Context +Source at a particular point in time, but only which entity +instances are possibly available from a Context Source, thus in this case the +information about available entity types and attributes is to be +interpreted as "possibly available". Also, context registrations can +have different granularities, i.e. they possibly only contain entity +type or attribute information, and thus the provided information about +available entity types and attributes is possibly incomplete as a +result. In particular the attributeNames in the EntityType +data structure (clause +5.2.25), the attributeDetails in the EntityTypeInfo +data structure (clause +5.2.26), and the attributeTypes and typeNames in the +Attribute data structure (clause +5.2.27) may be provided as empty arrays if the information is not +included in the respective context registration. Implementations may +also provide estimates for the entity count or attribute count instead +of the accurate count.

+

As an alternative to relying on local information only, the request +can be forwarded to all Context +Sources which support the respective operation according to the +Context Source Registration +describing them. In this case the returned lists are merged with the +local list of entity types before returning them. This approach is more +expensive but leads to a more accurate result.

+

5.8 Context Information +Subscription

+

5.8.1 Create +Subscription

+

5.8.1.1 Description

+

This operation allows creating a new subscription.

+

5.8.1.2 Use case +diagram

+

A Context Subscriber can create a subscription to receive +context updates within an NGSI-LD system as shown in Figure +5.8.1.2‑1.

+
+ +
+
+Figure 5.8.1.2-1: Create subscription use case +
+

5.8.1.3 Input data

+
    +
  • +A data structure (represented in JSON-LD) conforming to the +Subscription data type as mandated by clause +5.2.12. +
    • +
+

5.8.1.4 Behaviour

+
    +
  • +If the data types, cardinalities and restrictions expressed by clause +5.2.12 are not met, then an error of type BadRequestData +shall be raised. +
    • +
  • +If the NGSI-LD endpoint already knows about this Subscription, as there +is an existing Subscription whose id (URI) is equivalent, an error of +type AlreadyExists shall be raised. +
    • +
  • +If the subscription document does not include a Subscription identifier, +a new identifier (URI) shall be automatically generated by the +implementation. +
    • +
  • +Then, implementations shall add a new Subscription. The parameters of +the created Subscription shall be configured as follows: +
    • +
+
    +
  • +The Subscription expiration date shall be equal to the value of the +expiresAt member. If the expiration timestamp provided represents +a moment before the current date and time, then an error of type +BadRequestData shall be raised. If there is no expiresAt +member the Subscription shall be considered as perpetual. +
    • +
  • +If the value of the isActive field is not included or is +true then the initial status of the Subscription shall be set to +"active". +
    • +
  • +If the value of the isActive field is false, then the +initial status of the Subscription shall be set to "paused". +
    • +
  • +If present, the subscribed entities shall be those matching the +conditions expressed under the EntitySelector, as defined in clause +5.2.33. +
    • +
  • +Watched Attributes shall be those Attributes (subject to clause +5.5.7 Term to URI expansion) pertaining to the subscribed entities +(if present) and conveyed through the watchedAttributes member. +Watched Attributes are those that trigger a new notification when they +are changed. A non-present watchedAttributes member means that +all Attributes shall be watched. If no subscribed entities have been +specified, all entities with attributes matching at least one member of +watchedAttributes are subscribed to. +
    • +
  • +The @context to be used for sending Notifications related to this +Subscription shall be the one specified in the jsonldContext +field. If not present, the jsonldContext field shall be +initialized with the @context applicable for the Subscription (if +@context is also not present in the Subscription, see clause +5.5.5). When the remote JSON-LD @context referenced by the +jsonldContext field is not available implementations shall raise +an error of type LdContextNotAvailable. If the remote JSON-LD +@context referenced by the jsonldContext field is invalid, +implementations shall raise an error of type BadRequestData. +
    • +
  • +Based on the content of the Subscription, a Context Source Registration Subscription +shall be created (clause +5.11.2). The mapping of the id of the Subscription to the +returned subscriptionId of the Context Source Registration Subscription +shall be stored to enable updating or deleting the Context Source Registration Subscription in +case of changes to the Subscription. +
    • +
+
    +
  • +If the subscription defines a timeInterval member, a Notification +shall be sent periodically, when the time interval (in seconds) +specified in such value field is reached, regardless of Attribute +changes. +
    • +
  • +If timeInterval is not defined, whenever there is a change in the +watched Attribute nodes (Properties or Relationships) of the concerned +Entities, implementations shall post a new Notification as per the rules +defined by clause +5.8.6. +
    • +
  • +Each time a Context Source +Notification with the subscriptionId of the previously created +Context Source Registration +Subscription is received, implementations shall do the following: +
    • +
+
    +
  • +For any exclusive, redirect and +inclusive Context Source +Registration received as part of the notification, implementation +shall do the following depending on the triggerReason: +
    • +
+
    +
  • +If the triggerReason is "newlyMatching" and the Context Source Registration indicates +support for the Create Subscription operation, a copy of the original +Subscription shall be reduced to what is matched by the registration +information. If the splitEntities member is explicitly set to +true or, if not explicitly set, the default setting of the deployment +allows split entities, the members q, geoQ and +scopeQ shall be removed from the created copy of the original +Subscription. Also from the notification member, the +attributes, pick and omit members are to be +removed. The copied Subscription is then forwarded to the Context Source as a new Subscription where +the notification endpoint is set to that of the local Broker. The +mapping of the received subscriptionId with the own Subscription +identifier is stored to enable forwarding received notifications to the +original subscriber. In addition, a mapping of the id of the Context Source Registration to the received +subscriptionId is stored, to enable updating or deleting the +subscription in case of changes. +
    • +
  • +If the triggerReason is "updated" +and the Context Source Registration +indicates support for the Update Subscription operation, an update of +the original Subscription, reduced to what is matched by the +registration information, shall be created. If the splitEntities +member is explicitly set to true or, if not explicitly set, the default +setting of the deployment allows split entities, the members q, +geoQ and scopeQ shall be removed from the updated +Subscription. Also from the notification member the +attributes, pick and omit members are to be +removed. The updated Subscription is then forwarded to the Context Source with the +subscriptionId related to the Context +Source Registration. As an optimization, an implementation may +keep the originally forwarded Context Source +Registration and compare with the new one to only forward the +update, if there was a relevant change. +
    • +
  • +If the triggerReason is "noLongerMatching" and the Context Source Registration indicates +support for the delete Subscription operation, a delete Subscription +shall be forwarded to the Context +Source with the subscriptionId related to the Context Source Registration. +
    • +
+
    +
  • +Implementations shall ensure that, when the Subscription expiration date +is due, the status of the Subscription changes automatically to "expired", so +that notifications will no longer be sent. +
    • +
+

5.8.1.5 Output +data

+

One subscription identifier (id) of type string, representing a URI. +Implementations shall ensure that subscription identifiers are unique +within an NGSI-LD system.

+

5.8.2 Update +Subscription

+

5.8.2.1 Description

+

This operation allows updating an existing subscription.

+

5.8.2.2 Use case +diagram

+

A Context Subscriber can update an existing subscription +within an NGSI-LD system as shown in Figure +5.8.2.2‑1.

+
+ +
+
+Figure 5.8.2.2-1: Update subscription use case +
+

5.8.2.3 Input data

+
    +
  • +Subscription identifier (URI), the target subscription. +
    • +
  • +A JSON-LD document representing a Subscription Fragment. +
    • +
+

5.8.2.4 Behaviour

+
    +
  • +If the Subscription id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD System does not know about the target Subscription, +because there is no existing Subscription whose id (URI) is equivalent, +an error of type ResourceNotFound shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.12 are not met by the Subscription Fragment, then an +error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +If the jsonldContext field is present and the referenced JSON-LD +@context is not available, implementations shall raise an error +of type LdContextNotAvailable. If the referenced JSON-LD +@context is invalid, implementations shall raise an error of type +BadRequestData. +
    • +
  • +Then, implementations shall modify the target Subscription as mandated +by clause +5.5.8. +
    • +
  • +Finally, the following extra behaviour shall be observed when updating +Subscriptions: +
    • +
+
    +
  • +If isActive is equal to true and expiresAt is not +present, then status shall be updated to "active", if and only if, the previous value of +status was different than "expired". +
    • +
  • +If isActive is equal to true and expiresAt +corresponds to a DateTime in the future, then status shall +be updated to "active". +
    • +
  • +If isActive is equal to false and expiresAt is not +present, then status shall be updated to "paused", if and only if, the previous value of +status was different than "expired". +
    • +
  • +If only expiresAt is included and refers to a DateTime in +the future, then status shall be updated to "active", if and only if the previous value of +status was "expired". +
    • +
  • +If expiresAt is included but referring to a DateTime in +the past, then a BadRequestData error shall be raised, regardless +the value of isActive. +
    • +
  • +Based on the mapping of the Subscription to its respective Context Source Registration Subscription +(see clause +5.8.1.4), that Context Source +Registration Subscription shall be updated (clause +5.11.3). +
    • +
+

5.8.2.5 Output +data

+

None.

+

5.8.3 Retrieve +Subscription

+

5.8.3.1 Description

+

This operation allows retrieving an existing subscription.

+

5.8.3.2 Use case +diagram

+

A Context Subscriber can retrieve a specific subscription from +an NGSI-LD system as shown in Figure +5.8.3.2‑1.

+
+ +
+
+Figure 5.8.3.2-1: Retrieve subscription use case +
+

5.8.3.3 Input data

+

Id (URI) of the subscription to be retrieved (target +subscription).

+

5.8.3.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the identifier provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall query the subscriptions and obtain the +subscription data to be returned to the caller. +
    • +
+

5.8.3.5 Output +data

+

A JSON-LD object representing the subscription details as mandated by +clause +5.2.12.

+

5.8.4 Query +Subscriptions

+

5.8.4.1 Description

+

This operation allows querying existing Subscriptions.

+

5.8.4.2 Use case +diagram

+

A Context Consumer can query the +existent Subscriptions from an NGSI-LD system as shown in Figure +5.8.4.2‑1.

+
+ +
+
+Figure 5.8.4.2-1: Query subscriptions use case +
+

5.8.4.3 Input data

+

A limit to the number of subscriptions to be retrieved. See clause +5.5.9.

+

5.8.4.4 Behaviour

+
    +
  • +The NGSI-LD system shall list all the existing subscriptions up to the +limit specified as input data. If no limit is specified the number of +subscriptions retrieved may depend on the implementation. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.8.4.5 Output +data

+

A list (represented as a JSON array) of JSON-LD objects each one +representing subscription details as mandated by clause +5.2.12.

+

5.8.5 Delete +Subscription

+

5.8.5.1 Description

+

This operation allows deleting an existing subscription.

+

5.8.5.2 Use case +diagram

+

A Context Subscriber can delete a subscription within an +NGSI-LD system as shown in Figure +5.8.5.2‑1.

+
+ +
+
+Figure 5.8.5.2-1: Delete subscription use case +
+

5.8.5.3 Input data

+

A subscription identifier (URI).

+

5.8.5.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the subscription id provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall delete the Subscription and no longer +perform notifications concerning such Subscription. +
    • +
  • +Using the mapping of the own Subscription identifier to each of the +subscriptionId of a subscription to a Context Source, a delete Subscription shall +be forwarded to each such Context +Source, if the delete Subscription operation is supported as +indicated in the corresponding Context +Source Registration: +
    • +
+
    +
  • +Based on the mapping of the Subscription to its respective Context Source Registration Subscription +(see clause +5.8.1.4), that Context Source +Registration Subscription shall be deleted (clause +5.11.6). +
    • +
+

5.8.5.5 Output +data

+

None.

+

5.8.6 Notification behaviour

+

A notification is a message that allows a subscriber to be aware of +the changes in subscribed Entities. Implementations shall exhibit the +following behaviour:

+
    +
  • +Notifications shall only be sent if and only if the status of the +corresponding subscription (subscription.status) is "active", i.e. +not "paused" nor "expired". +
    • +
  • +If a Subscription defines a timeInterval member, a Notification +shall be sent periodically, when the time interval (in seconds) +specified in such value field is reached, regardless of Attribute +changes. The notification message shall include all the subscribed +Entities that match the query, geoquery and Scope query conditions. If +none of query, geoquery and Scope query are defined, then all subscribed +Entities shall be included. For each entity in the notification, only +the Attribute instances are to be included that match the +datasetId member in Subscription. If there are no matching +Entities, no Notification is sent. +
    • +
  • +If a Subscription does not define a timeInterval term, the +notification shall be sent whenever there is a change in the watched +Attributes. An Attribute is considered to change when any of the members +(including children) in its corresponding JSON-LD node is updated with a +value different than the existing one. The notification message shall +include all the subscribed Entities that changed and that match (as +mandated by clauses 4.9, +4.10 +and 4.19) +the query, geoquery and Scope query conditions. If query, geoquery and +scopeQuery are all not defined then all subscribed Entities that changed +shall be included. If, for an Entity, there are multiple instances of +the GeoProperty on which the geoquery is based, it is sufficient +if any of these instances meets the geospatial restrictions. For each +entity in the notification, only the Attribute instances are to be +included that match the datasetId member in Subscription. +Finally, if a Context Source filter +is defined, then only the subscribed Entities whose origin Context Source matches the referred filter +shall be included. +
    • +
  • +If a Notification with a subscriptionId is received that has a +mapping to a local Subscription identifier, the Notification shall be +copied.
    +If the splitEntities member of the local Subscription is +explicitly set to true or, if not explicitly set, the default setting of +the deployment allows split entities, +
    • +
+
    +
  • +the Entities contained in the data member of the Notification shall be +retrieved locally and from all Context Sources that have information +about these Entities, except for the one from which the Notification has +been received. +
    • +
  • +The retrieved Entities then shall be merged with the Entities in the +data member. +
    • +
  • +All Entities that do not match the query, geoquery and Scope query +conditions of the local Subscription shall be removed from the data +member. +
    • +
+
    +
  • +If there are Entities in the data member of the Notification +copy, the Notification copy shall be forwarded to the Notification +endpoint specified in the local Subscription, using this local +Subscription identifier instead of the subscriptionId +received. +
    • +
  • +A Notification shall be sent as follows: +
    • +
+
    +
  • +The structure of the notification message shall be as mandated by clause +5.3.1. +
    • +
  • +The @context to be used is the one specified in the +jsonldContext field of the corresponding Subscription. +
    • +
  • +The Attributes included (Properties or Relationships) +shall be those specified by the notification.attributes member in +the Subscription data type (clause +5.2.12). Term to URI expansion shall be observed (clause +5.5.7). The absence of the notification.attributes member of +a Subscription means that all Attributes shall be included. If the +notification was triggered by the deletion of an Entity and the +notification.showChanges member is not set to true, only +the deletedAt system property shall be provided. In case +notification.sysAttrs is set to true, also +createdAt and modifiedAt shall be provided. +
    • +
  • +If an Attribute has been deleted, only the name of the attribute as key +and the URI "urn:ngsi-ld:null" as value +shall be provided, unless more information is required. The latter is +the case, if: +
    • +
+
    +
  • +a datasetId needs to be provided; +
    • +
  • +the notification.sysAttrs is set to true and thus the +system generated sub-attributes (see clause +4.8) have to be provided; +
    • +
  • +notification.showChanges is set to true and thus a +previous value or object has to be provided. +
    • +
+
+ In all such cases, a JSON object with all the required information is +provided, where the value or the object is set to the URI +"urn:ngsi-ld:null" respectively or, in +case of a LanguageProperty, the languageMap is set to +{"@none": "urn:ngsi-ld:null"}. +
+
    +
  • +If the +notification.formatmember value is set, the +representation of the entities changes: +
    • +
+
    +
  • +If the notification.format is set to "concise" then a concise representation of the +entities shall be provided as defined by clause +4.5.1. +
    • +
  • +If the notification.format is set to "simplified" (or "keyValues" as a synonym), then a simplified +representation of the entities (as mandated by clause +4.5.4) shall be provided. +
    • +
  • +Otherwise the normalized format as defined by clause +4.5.1 shall be used. +
    • +
+
    +
  • +If the +notification.pickmember value is set, every +Entity within the payload body is reduced down to only contain the +defined entity members listed. +
    • +
  • +If the +notification.omitmember value is set, the +defined entity members listed are removed from each Entity within the +payload. +
    • +
  • +If the +notification.joinmember value is set then Linked Entityretrieval(as mandated by clause 4.5.23) shall be +provided. +
    • +
  • +If the ngsildConformance field of the corresponding Subscription +is set, the notification shall undergo a backwards compatibility +operation as defined by clause +4.3.6.8 and be amended to conform to the supplied version of the +NGSI-LD specification. +
    • +
  • +A Notification shall be sent +(as mandated by each concrete binding and including any optional +endpoint.receiverInfodefined by clause 5.2.22) to the endpoint specified by the +endpoint.urimember of the notification structure +defined by clause 5.2.14. The Notification content +shall be JSONby default. +However, this can be changed to JSON-LD or GeoJSONby means of the +endpoint.acceptmember. +
    • +
  • +The notification.timesSent member shall be incremented by one. +
    • +
  • +The notification.lastNotification member shall be updated with a +timestamp representing the current date and time. +
    • +
  • +If the response to the notification request is 200 OK then +implementations shall: +
    • +
+
    +
  • +Update notification.lastSuccess with a timestamp representing the +current date and time. +
    • +
  • +Update notification.status to "ok". +
    • +
+
    +
  • +If the response to the +notification request is different than 200 OKthen implementations shall: +
    • +
+
    +
  • +Update notification.lastFailure with a timestamp representing the +current date and time. +
    • +
  • +Update notification. Status to "failed". +
    • +
+

5.9 Context +Source Registration

+

5.9.1 Introduction

+

As described in clause +5.2.9, Context Source +Registrations have a similar structure as Entities and are +generally handled in the same way. However, there are some aspects that +are specific to Registrations, in particular with respect to the +handling of required properties. Thus, the operation descriptions for +Registrations reference the respective operations for Entities and in +addition specify any deviations and additions that are necessary for +handling Context Source +Registrations.

+

Context Source Registrations +either contain information about Context +Sources providing the latest information or about Context Sources providing temporal +information, but not both. Context +Sources that can provide both thus have to use two separate Context Source Registrations. If no +temporal query is present, only Context +Source Registrations for Context +Sources providing latest information are returned, i.e. those +which do not specify time intervals used for temporal queries. If a +temporal query is present in a request for Context Source Registrations, only those +Context Source Registrations that +have a matching time interval are returned.

+

5.9.2 Register +Context Source

+

5.9.2.1 Description

+

This operation allows registering a context source within an NGSI-LD +system.

+

5.9.2.2 Use case +diagram

+

A Context Provider can register one or more context sources +within an NGSI-LD system as shown in Figure +5.9.2.2‑1.

+
+ +
+
+Figure 5.9.2.2-1: Register context source use case +
+

5.9.2.3 Input data

+

A data structure conforming to the CSourceRegistration data +type as mandated by clause +5.2.9.

+

5.9.2.4 Behaviour

+

Implementations shall generally exhibit the behaviour described in clause +5.6.1.4, but instead of any type of entities only Context Source Registrations can be +provided. Deviating from clause +5.6.1.4, implementations shall exhibit the following behaviour:

+
    +
  • +If the data types and restrictions expressed by clause +5.2.9 are not met by the Context Source +Registration, then an error of type BadRequestData shall +be raised. +
    • +
  • +If a contextSourceInfo array is defined and the restrictions +expressed by clause +4.3.6.6 are not met by the Context +Source Registration, then an error of type BadRequestData +shall be raised. +
    • +
  • +If the Context Source to be +registered has its mode property defined as +exclusive, the following additional restrictions apply: +
    • +
+
    +
  • +If an exclusive or redirect Context Source Registration already matches +against the Entity ID (URI) and any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
  • +If an Entity already exists for the supplied Entity ID (URI) and the +existing Entity contains any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be +registered has its mode property defined as +redirect, the following additional restriction applies: +
    • +
+
    +
  • +If an existing Entity already matches the Context Source Registration, an error of +type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be +registered has its mode property defined as +auxiliary, the following additional restriction +applies: +
    • +
+
    +
  • +If the operations property is not defined as one of: "retrieveOps", "retrieveEntity" or "queryEntity", +or a combination thereof, an error of type BadRequestData shall +be raised. +
    • +
+
    +
  • +If the property expiresAt is not defined then the Context Source Registration shall last +forever (or until it is deleted from the system). +
    • +
  • +If expiresAt is a date and time in the past, an error of type +BadRequestData shall be raised. +
    • +
  • +If expiresAt is a date and time in the future, implementations +shall delete the Registration when this point in time is reached. +
    • +
  • +If the registration identifier, id, is contained in the Context Source Registration, +implementations have to check whether this is a valid identifier that +conforms to its policies and is unique within its scope. Otherwise, it +can replace the 'id' with a valid registration identifier. +
    • +
  • +Implementations shall add the concerned Context Source Registration and return an +'ok' response together with a registration identifier (id). +
    • +
  • +This id shall be used if NGSI-LD clients need to manage the +registration later. +
    • +
+

5.9.2.5 Output +data

+

One registration identifier (id) of type string, representing +a URI. Implementations shall ensure that registration identifiers are +unique within an NGSI-LD system.

+

5.9.3 Update Context Source +Registration

+

5.9.3.1 Description

+

This operation allows updating a Context +Source Registration in an NGSI-LD system.

+

5.9.3.2 Use case +diagram

+

A Context Provider can update a Context Source Registration in an NGSI-LD +system as shown in Figure +5.9.3.2‑1.

+
+ +
+
+Figure 5.9.3.2-1: Update context source registration use case +
+

5.9.3.3 Input data

+
    +
  • +Context Source Registration +identifier (URI), the target Context Source +Registration. +
    • +
  • +A JSON-LD document representing a Context +Source Registration Fragment (clause +5.4). +
    • +
+

5.9.3.4 Behaviour

+
    +
  • +If the target Context Source +Registration id (id) is not present or it is not a valid +URI, then an error of type BadRequestData shall be raised. +
    • +
  • +If a "contextSourceInfo" array is defined and the restrictions expressed +by clause +4.3.6.6 are not met by the Context +Source Registration, then an error of type BadRequestData +shall be raised. +
    • +
  • +If the NGSI-LD System does not know about the target Context Source Registration, because there +is no existing Context Source +Registration whose id (URI) is equivalent, an error of type +ResourceNotFound shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.9 are not met by the Context Source +Registration Fragment, then an error of type +BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +If the Context Source Registration to +be updated has its mode property defined as +exclusive, the following additional restrictions apply: +
    • +
+
    +
  • +If an exclusive or redirect Context Source Registration already matches +against the Entity ID (URI) and any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
  • +If an Entity already exists for the supplied Entity ID (URI) and the +existing Entity contains any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source Registration to +be updated has its mode property defined as +redirect, the following additional restriction applies: +
    • +
+
    +
  • +If an existing Entity already matches the Context Source Registration, an error of +type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be updated +has its mode property defined as auxiliary, the +following additional restriction applies: +
    • +
+
    +
  • +If the operations property is not defined +as one of: "retrieveOps", "retrieveEntity" or "queryEntity", an error of type +BadRequestData shall be raised. +
    • +
+
    +
  • +Then, implementations shall modify the target Context Source Registration as mandated by +clause +5.5.8. +
    • +
+

5.9.3.5 Output +data

+

None.

+

5.9.4 Delete Context Source +Registration

+

5.9.4.1 Description

+

This operation allows deleting a Context +Source Registration from an NGSI-LD system.

+

5.9.4.2 Use case +diagram

+

A context provider can delete a context source registration from an +NGSI-LD system as shown in Figure +5.9.4.2‑1.

+
+ +
+
+Figure 5.9.4.2-1: Delete context source registration use case +
+

5.9.4.3 Input data

+

Registration identifier (URI) of the context source registration to +be deleted (target registration).

+

5.9.4.4 Behaviour

+
    +
  • +If the target context source registration id is not present or it is not +a valid URI, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target context source +registration, because there is no existing context source registration +whose id (URI) is equivalent, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Otherwise the context source registration shall be removed. +
    • +
+

5.9.4.5 Output +data

+

None.

+

5.10 Context +Source Discovery

+

5.10.1 Retrieve Context +Source Registration

+

5.10.1.1 Description

+

This operation allows retrieving a specific context source +registration from an NGSI-LD system.

+

5.10.1.2 Use case +diagram

+

A context consumer or a context provider can retrieve a specific +context source registration from an NGSI-LD system as shown in Figure +5.10.1.2‑1.

+
+ +
+
+Figure 5.10.1.2-1: Retrieve context source registration use case +
+

5.10.1.3 Input +data

+

Context source registration identifier (id) of the context source +registration to be retrieved (target registration).

+

5.10.1.4 Behaviour

+
    +
  • +If the context source registration id (id) is not present or it +is not a valid URI, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target context source +registration, because there is no existing context source registration +whose id (URI) is equivalent, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +Otherwise return a JSON-LD object representing the Context Source Registration as mandated by +clause +5.2.9. +
    • +
+

5.10.1.5 Output +data

+

A JSON-LD object representing the target context source registration +as mandated by clause +5.2.9.

+

5.10.2 Query Context Source +Registrations

+

5.10.2.1 Description

+

This operation allows discovering context source registrations from +an NGSI-LD system. The behaviour of the discovery of context source +registrations differs significantly from the querying of entities as +described in clause +5.7.2. The approach is that the client submits a query for entities +as described in clause +5.7.2, but instead of receiving the Entity information, it receives +a list of Context Source +Registrations describing Context +Sources that possibly have some of the requested Entity +information. This means that the requested Entities and Attributes are +matched against the 'information' property as described in .

+

If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without specified time intervals, are considered. If a +temporal query is present only Context +Source Registrations with matching time intervals, i.e. +observationInterval or managementInterval, are +considered.

+

5.10.2.2 Use case +diagram

+

A Context Consumer can discover context source registrations +that may be able to provide (part of) the context information specified +in the query from an NGSI-LD system as shown in Figure +5.10.2.2‑1.

+
+ +
+
+Figure 5.10.2.2-1: Discover context source registrations use case +
+

5.10.2.3 Input +data

+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17. Both type name (short hand string) and fully qualified type +name (URI) are allowed (optional). +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names (called query projection +attributes) (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values, used here +to identify relevant attributes) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships, +used here to identify relevant GeoProperties and for geographical +scoping) as per clause +4.10 (optional). +
    • +
  • +In the case of GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +An NGSI-LD temporal query as per clause +4.11 (optional). +
    • +
  • +An NGSI-LD context source query as per clause +4.9 (optional). +
    • +
  • +A NGSI-LD Scope query as mandated by clause +4.19 (optional). +
    • +
  • +A limit to the number of Context Source +Registrations to be retrieved. See clause +5.5.9. +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
+

It is not possible to retrieve a set of context source registrations +related to entities by only specifying desired Entity identifiers, +without further specifying restrictions on the entities' types or +attributes, either explicitly, via lists of Entity types or of Attribute +names, or implicitly, within an NGSI-LD query or geoquery.

+

5.10.2.4 Behaviour

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names; +
+
+c) NGSI-LD Query; +
+
+d) NGSI-LD GeoQuery. +
+
+ If none of them is provided, then an error of type BadRequestData +shall be raised (too wide query). Attributes specified in NGSI-LD Query +or NGSI-LD GeoQuery shall be used for matching RegistrationInfo elements +in the same way as the attributes in the list of Attribute names. +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or temporal query are not syntactically valid (as +per clauses 4.9, +4.10 +and 4.11) +an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
    • +
  • +Otherwise, implementations shall run a query that shall return context +source registrations that meet all the applicable +conditions: +
    • +
+
    +
  • +If present, the entity specification in the query consisting of a +combination of entity type selector and entity id/entity id pattern +(optional) matches an EntityInfo specified in a +RegistrationInfo of the information property in a context source +registration. If there is no EntityInfo specified in the +RegistrationInfo, the entity specification is considered +matching. This matching is further described in . +
    • +
  • +If present, at least one Attribute name specified in the query matches +one Property or Relationship in the RegistrationInfo element of +the information property in a context source registration. If no +Properties or Relationships are specified in the +RegistrationInfo, the Attribute names are considered matching. +This matching is further described in . +
    • +
  • +If present, the geoquery is matched against the GeoProperty +identified in the geoquery. If no GeoProperty is specified in the +geoquery, the default property is location. The geoquery matches +the GeoProperty specified in the Context Source Registration, if the +location directly matches or if the location possibly contains locations +that would match the geoquery. +
    • +
  • +If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without specified time intervals, are considered. +
    • +
  • +If a temporal query is present, only Context +Source Registrations with specified time intervals, i.e. +observationInterval or managementInterval are considered. +If the timeproperty is observedAt or no +timeproperty is specified in the temporal query (default: +observedAt), the temporal query is matched against the +observationInterval (if present). If the timeproperty is +createdAt, modifiedAt or deletedAt, the temporal +query is matched against the managementInterval (if present). If +the relevant interval is not present, there is no match: +
    • +
+
    +
  • +The semantics of the match is that the timeAt in the case of the +"before" and "after" relation is contained in or is an +endpoint of a time period included in the specified time interval. In +the case of the "between" relation there +is a match if there is an overlap between the interval specified by the +timeAt and endTimeAt and the specified time interval. +
    • +
+
    +
  • +If present, the conditions specified by the context source query filter +match the respective Context Source +Properties (as mandated by clause +4.9). +
    • +
  • +If present, the Scope query (as mandated by clause +4.19) is matched against the scope property. +
    • +
+
    +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.10.2.5 Output +data

+

A JSON-LD array of matching Context +Source Registrations as defined by clause +5.2.9. Instead of the original Context +Source Registration which may contain a lot of irrelevant +information, implementations should return filtered Context Source Registrations, which only +contain context source registration information relevant for the query, +in particular only matching RegistrationInfo elements.

+

5.11 Context Source +Registration Subscription

+

5.11.1 Introduction

+

Context Source Registration +Subscriptions in general work like context information subscriptions; +however, instead of resulting in notifications with context information, +the notifications contain Context Source +Registrations describing Context +Sources that can potentially provide the requested context +information. If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without such time intervals, are considered. If a +temporal query is present only Context +Source Registrations with matching time intervals, i.e. +observationInterval or managementInterval, are +considered.

+

5.11.2 Create +Context Source Registration Subscription

+

5.11.2.1 Description

+

This operation allows creating a new Context Source Registration +Subscription.

+

5.11.2.2 Use case +diagram

+

A Context Source Subscriber +can subscribe to a new Context Source +Registration as shown in Figure +5.11.2.2‑1.

+
+ +
+
+Figure 5.11.2.2-1: Subscribe Context Source Registration use case +
+

5.11.2.3 Input +data

+
    +
  • +A data structure (represented in JSON-LD) conforming to the Subscription +data type as mandated by clause +5.2.12. +
    • +
+

5.11.2.4 Behaviour

+
    +
  • +The behaviour shall be as described in clause +5.8.1.4, restricted to the local case, with the following +exceptions: +
    • +
+
    +
  • +If an exclusive Context +Source Registration is being created: +
    • +
+
    +
  • +If an Entity matching the Registration already exists for this id (URI) +and attributes, an error of type Conflict shall be raised. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI) and +attributes, an error of type AlreadyExists shall be raised. +
    • +
+
    +
  • +If a redirect Context +Source Registration is being created and an Entity matching the +Registration already exists for this id (URI) and attributes, an error +of type Conflict shall be raised. +
    • +
  • +If all checks described in clause +5.8.1.4 pass, implementations shall add a new Context Source Registration Subscription. +The parameters of the created subscription shall be configured as +described in clause +5.8.1.4. +
    • +
  • +Instead of directly matching the entities and watched Attributes from +the Subscription with the Context +Source registrations, the entities specified in the subscription, +the watched Attributes and the Attributes specified in the notification +parameter are matched against the respective information property +of the Context Source registrations. +If either the watched Attributes or the Attributes in the notification +are not present or of length 0, all possible Attributes (if present in +the Context Source Registrations) for +matching entities match. This matching is further described in . +
    • +
  • +If present, the geoquery in the geoQ element is matched against the +GeoProperty of the subscription identified in the geoQ element. +If no GeoProperty is specified in the geoquery, the default +property is 'location'. The geoquery matches the GeoProperty +specified in the Context Source +Registration, if the location directly matches or if the location +possibly contains locations that would match the geoquery. +
    • +
  • +If no temporal query is present in the temporalQ element, only +Context Source Registrations for +Context Sources providing latest +information, i.e. without specified time intervals for +observationInterval or managementInterval, are considered. +
    • +
  • +If a temporal query in the temporalQ element is present, only +Context Source Registrations with +specified time intervals are considered. If the timeproperty is +"observedAt" or +no timeproperty is specified in the temporal query (default: +observedAt), the temporal query is matched against the +observationInterval (if present). If the timeproperty is +"createdAt", +"modifiedAt" +or "deletedAt", the temporal query is matched against the +managementInterval (if present). If the relevant interval is not +present, there is no match: +
    • +
+
    +
  • +The semantics of the match is that the timeAt in the case of the +"before" and "after" relation is contained in or is an +endpoint of a time period included in the specified time interval. In +the case of the "between" relation there +is a match if there is an overlap between the interval specified by the +timeAt and endTimeAt and the specified time interval. +
    • +
+
    +
  • +If present, the conditions specified by the context source filter match +the respective Context Source +Properties (as mandated by clause +4.9). +
    • +
+
    +
  • +If the subscription defines a timeInterval term, a +CsourceNotification (clause +5.3.2) with all matching Context Source +Registrations shall be sent periodically, initially on +subscription and when the time interval (in seconds) specified in such +value field is reached, independent of any changes to the set of Context Source registrations. +
    • +
  • +If timeInterval is not defined, initially on subscription and +whenever there is a change of a matching Context Source Registration (creation, +update, deletion), implementations shall post a new +CsourceNotification to the endpoint specified in the notification +parameters informing about this change by providing the Context Source Registration(s) together +with the appropriate trigger reason in the triggerReason member. +
    • +
  • +If present, the conditions specified by the context source query match +the respective Context Source +Properties (as mandated by clause +4.9). +
    • +
  • +If present, the Scope query (as mandated by clause +4.19) is matched against the scope property. +
    • +
+

5.11.2.5 Output +data

+

One subscription identifier (id) of type string, representing a URI. +Implementations shall ensure that subscription identifiers are unique +within an NGSI-LD system.

+

5.11.3 Update +Context Source Registration Subscription

+

5.11.3.1 Description

+

This operation allows updating an existing Context Source Registration +Subscription.

+

5.11.3.2 Use case +diagram

+

A context source subscriber can update a Context Source Registration Subscription as +shown in Figure +5.11.3.2‑1.

+
+ +
+
+Figure 5.11.3.2-1: Update Context Source Registration Subscription use +case +
+

5.11.3.3 Input +data

+
    +
  • +Subscription identifier (URI), the target Context Source Registration Subscription. +
    • +
  • +A JSON-LD document representing a Subscription Fragment. +
    • +
+

5.11.3.4 Behaviour

+
    +
  • +If the Subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.12 are not met by the Subscription Fragment, then an error of +type BadRequestData shall be raised. +
    • +
  • +Then, implementations shall modify the target subscription as mandated +by clause +5.5.8. +
    • +
  • +Finally, send a notification with all currently matching Context Source Registrations. +
    • +
+

5.11.3.5 Output +data

+

None.

+

5.11.4 Retrieve +Context Source Registration Subscription

+

5.11.4.1 Description

+

This operation allows retrieving an existing Context Source Registration +Subscription.

+

5.11.4.2 Use case +diagram

+

A Context Source subscriber can +retrieve a specific Context Source +Registration Subscription as shown in Figure +5.11.4.2‑1.

+
+ +
+
+Figure 5.11.4.2-1: Retrieve Context Source Registration Subscription use +case +
+

5.11.4.3 Input +data

+

Id (URI) of the subscription to be retrieved (target +subscription).

+

5.11.4.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the identifier provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall query the Context Source Registration Subscriptions +and obtain the subscription data to be returned to the caller. +
    • +
+

5.11.4.5 Output +data

+

A JSON-LD object representing the subscription details as mandated by +clause +5.2.12.

+

5.11.5 Query +Context Source Registration Subscriptions

+

5.11.5.1 Description

+

This operation allows querying existing Context Source Registration +Subscriptions.

+

5.11.5.2 Use case +diagram

+

A context source subscriber can query all existing Context Source Registration Subscriptions +as shown in Figure +5.11.5.2‑1.

+
+ +
+
+Figure 5.11.5.2-1: Query Context Source Registration Subscriptions use +case +
+

5.11.5.3 Input +data

+

A limit to the number of Context Source +Registration Subscriptions to be retrieved. See clause +5.5.9.

+

5.11.5.4 Behaviour

+
    +
  • +The NGSI-LD System shall list all the existing Context Source Registration Subscriptions. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.11.5.5 Output +data

+

A list (represented as a JSON array) of JSON-LD objects each one +representing subscription details as mandated by clause +5.2.12.

+

5.11.6 Delete +Context Source Registration Subscription

+

5.11.6.1 Description

+

This operation allows deleting an existing Context Source Registration +Subscription.

+

5.11.6.2 Use case +diagram

+

A context source subscriber can delete a Context Source Registration Subscription as +shown in Figure +5.11.6.2‑1.

+
+ +
+
+Figure 5.11.6.2-1: Delete Context Source Registration Subscriptions use +case +
+

5.11.6.3 Input +data

+
    +
  • +A subscription identifier (URI). +
    • +
+

5.11.6.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the subscription id provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall delete the Context Source Registration Subscription +and no longer perform notifications concerning that Subscription. +
    • +
+

5.11.6.5 Output +data

+

None.

+

5.11.7 Notification behaviour

+

A Context Source Notification is a +message that allows a subscriber to be aware of the changes in the set +of Context Source Registrations +describing Context Sources that can +potentially provide the requested context information. Implementations +shall exhibit the behaviour described in clause +5.8.6 with the following exceptions:

+
    +
  • +If a subscription defines a timeInterval member, a +CsourceNotification (clause +5.3.2) shall be sent on initial subscription and periodically, when +the time specified time interval (in seconds) has elapsed, regardless of +any changes to the set of context source registrations. The +CsourceNotification message shall include all the Context Source Registrations whose +information property matches the entities and watched Attributes +or Attributes specified in the notification parameter and, if present, +have a matching geoquery. If either the watched Attributes or the +Attributes in the notification are not present or of length 0, all +possible Attributes (if present in the Context Source Registrations) for fitting +entities match. +
    • +
  • +If a subscription does not define a timeInterval term, the +csource notification shall be sent on initial subscription and whenever +there is a change in a matching csource registration. Such a change may +be triggered by the creation of a new matching csource registration, the +update of a csource registration (whether matching before the update, +after the update or in both cases) or the deletion of a matching csource +registration. The notification message shall include the matching +csource registration(s) together with the appropriate trigger reason in +the triggerReason member. +
    • +
  • +Instead of providing the original Context +Source Registration which may contain a lot of irrelevant +information, implementations should return filtered Context Source Registrations, which only +contain context source registration information relevant for the +subscription, in particular only matching RegistrationInfo +elements. +
    • +
  • +A csource notification shall be sent as follows: +
    • +
+
    +
  • +The structure of the csource notification message shall be as mandated +by clause +5.3.2. +
    • +
  • +A csource notification shall be +sent to the endpoint. +
    • +
  • +The notification.timesSent member shall be incremented by one. +
    • +
  • +The notification.lastNotification member shall be updated with +the current timestamp. +
    • +
  • +If the notification is sent successfully: +
    • +
+
    +
  • +Update notification.lastSuccess with the current timestamp. +
    • +
+
    +
  • +If the notification is not sent +successfully: +
    • +
+
    +
  • +Update notification.lastFailure with the current timestamp. +
    • +
  • +Update the subscription status to "failed". +
    • +
+

5.12 Matching Context Source +Registrations

+

When querying Context Source +Registrations as described in clause +5.10.2 and subscribing to Context Source +Registrations as described in clause +5.11.2, the Entities and/or Attributes specified in the request have +to be matched against the set of Context +Source Registrations, extracting the matching ones. This clause +describes this matching.

+

The relevant specification information in the query for Context Source Registrations are the +selector of Entity Types (if present), the list of Entity identifiers +(if present), the id pattern (if present) and the list of Attribute +names (if present). In the case of subscriptions to Context Source Registrations, it is the +Entities as specified in the array of type EntitySelector in the +Subscription, the watchedAttributes element of the +Subscription and the attributes specified as part of the +NotificationParams element of the Subscription. If the attributes +in the NotificationParams element are empty or not present, the +matching is done as if no attribute identifiers have been specified, +otherwise the combination of the watchedAttributes and the +attributes in the NotificationParams element are used as the +specified attribute identifiers for the matching.

+

Even though the way relevant Entities are specified differs in +queries and subscriptions, they consist of the same information, so for +the purpose of this clause, the specification of Entity Types or +Attributes refers to the relevant elements for matching, i.e. Entity +Types, Entity identifiers, id pattern and Attribute names. A +specification of Entity Types or Attributes shall contain at least one +of:

+
    +
  1. +selector of Entity Types; or +
    2. +
  2. +list of Attribute names. +
    3. +
+

A specification of Entity Types or Attributes matches a Context Source Registration if at least one +of the RegistrationInfo elements in the information +element matches. An Entity specification matches a +RegistrationInfo if the following conditions hold:

+
    +
  • +If present, the selector of Entity Types, Entity identifiers and id +pattern match at least one of the EntityInfo elements of the +RegistrationInfo (see below). +
    • +
  • +If present, the Attribute identifiers match the combination of +Properties and Relationships specified in the RegistrationInfo +(see below). +
    • +
+

An Entity specification consisting of selector of Entity Types, +Entity identifiers and id pattern matches an EntityInfo element +of the RegistrationInfo if the type selector matches the entity +types in the EntityInfo element and one of the following +conditions holds:

+
    +
  • +The EntityInfo contains neither an id nor an +idPattern. +
    • +
  • +One of the specified Entity identifiers matches the id in the +EntityInfo. +
    • +
  • +At least one of the specified Entity identifiers matches the +idPattern in the EntityInfo. +
    • +
  • +The specified id pattern matches the id in the EntityInfo. +
    • +
  • +Both a specified id pattern and an idPattern in the +Entity Info are present (since in the general case it is not +easily feasible to determine if there can be identifiers matching both +patterns). +
    • +
+

Attribute names match the combination of Properties and Relationships +if one of the following conditions hold:

+
    +
  • +No Attribute names have been specified (as this means all Attributes are +requested). +
    • +
  • +The combination of Properties and Relationships is empty (as this means +only Entities have been registered and the Context Sources may have matching Property +or Relationship instances). +
    • +
  • +If at least one of the specified attribute names matches a Property or +Relationship specified in the RegistrationInfo. +
    • +
+

If the request that triggered the matching includes a +datasetId parameter and the CSourceRegistration to be matched +contains a datasetId element, the CSourceRegistration should only +be considered matching, if both have at least one value in common. If +only one of them specifies a datasetId, it is considered a +match.

+

In the case of distributed operations (see clause +4.3.6.4), where a listing of all previously encountered Context Sources is supplied with the +request, no registration shall match if the CSourceRegistration +contextSourceAlias can be found within the listing of previously +encountered Context Sources.

+

Note that distributed queries (see clause +4.3.6.7), can be supplied with an EntityMap (see clause +4.5.25) which lists all Entity ids successfully matched during a +previous request. If the location of an EntityMap is passed into a +subsequent request, the retrieved EntityMap shall be used in preference +to the matching algorithm described above, provided that the EntityMap +is valid and has not expired.

+

5.13 Storing, Managing and +Serving @contexts

+

5.13.1 Introduction

+

Context Brokers optionally (see clause +4.3.5) offer the capability to store and serve @contexts to +clients. The stored @contexts may be managed by clients directly, +via the APIs specified in clause +5.13. Clients can store custom user @contexts at the Context +Broker, effectively using the Context Broker as a @context +server.

+

Moreover, in order to optimize performance, brokers may automatically +store and use the stored copies of common @contexts as a local cache, +downloading them just once, thus avoiding fetching them over and over +again at each NGSI-LD request. In order for the broker to understand if +a needed @context is already in the local storage or not, the +broker uses the URL, where the @context is originally hosted, as +an identifier for it in the local storage. Consequently, the broker has +no ability to cache @contexts that arrive to it as +embedded parts within the NGSI-LD documents, since they +are not uniquely (and implicitly) identified by any URL; Context Brokers only cache @contexts +that are referred to by means of explicit URLs (either in the HTTP Link +header or as URLs in the payload body). Thus, the recommended +best-practice, in order to exploit caching, is that clients do not embed +their user @contexts into their NGSI-LD +documents; instead clients should explicitly host their user +@contexts at their premises, or use the broker's capability to +host user @contexts on their behalf.

+

When an external @context is stored, either explicitly upon a +client's request or implicitly downloaded for caching purposes, the +Context Broker generates a unique local @context identifier. The +original @context's URL, if any, is stored alongside the +generated local id. The local id is then used for subsequent managing +operations on the specific @context, that are specified in +clauses 5.13.2 to +5.13.5. Moreover, the broker tags the entry with the current timestamp, +(createdAt) so that, subsequently, clients can check the timestamp +before deciding whether to force a refresh of the stored copy of the +@context. This is primarily intended as a means for clients to +well-behave, thus avoiding triggering continuous refresh of a stored +@context on the broker, for fear that it is not at the latest +version.

+

Stored @contexts are flagged as one of three kinds: "Cached", "Hosted", "ImplicitlyCreated":

+
    +
  • +Cached:
    +@contexts implicitly and automatically fetched by the broker from +external URLs during normal NGSI-LD operations are flagged as "Cached". A locally unique identifier is +generated for each @context not already in the internal storage. +The downloaded content, its URL and the current time in UTC are stored +alongside the locally unique identifier. Implementations shall +periodically invalidate the "Cached" @contexts. Depending on the +binding of the NGSI-LD API to a specific protocol, that specific +protocol may provide explicit indications about expiration times of +cached content. In such cases, implementations shall comply with the +indications provided by the protocol. Implementations should assign a +heuristic expiration time when an explicit time is not specified. +Entries flagged as "Cached" shall not be served by brokers +on-demand, but only be used as a local cache to improve +performance. +
    • +
  • +Hosted:
    +@contexts that are explicitly added by users are flagged as "Hosted". These entries shall be served by +brokers on-demand. +
    • +
  • +ImplicitlyCreated:
    +@contexts that are implicitly, but ex-novo, created by the +broker as a result of a user request are flagged as "ImplicitlyCreated". For instance, when a +client creates a subscription using an @context that is an array, +and the broker has to notify with Content-Type "application/json", then the broker needs this @context +array to be hosted at a URL. Hence the broker has to create a new +@context that is an array, and it is going to be served from an +own URL. These entries shall be served by brokers on-demand. +
    • +
+

5.13.2 Add @context

+

5.13.2.1 Description

+

With this operation, a client can ask the broker to store the full +content of a specific @context, by giving it to the broker.

+

5.13.2.2 Use case +diagram

+

A client can add an @context to be stored within an NGSI-LD +system as shown in Figure +5.13.2.2‑1.

+
+ +
+
+Figure 5.13.2.2-1: Add @context use case +
+

5.13.2.3 Input +data

+

A JSON object that has a top-level field named @context, i.e. +a JSON object representing a JSON-LD "local context". As specified in +the JSON-LD specification [2], all extra information +located outside of the @context subtree in the referenced object +shall be discarded.

+

5.13.2.4 Behaviour

+

A new entry is created in the local storage and a locally unique +identifier is generated for it. The JSON object representing the +client-supplied @context and the current UTC time are stored +alongside the locally unique identifier. That identifier shall be given +back as a result in the output data. The entry is flagged as being of +kind "Hosted".

+

The behaviour described in clause +5.5.4 about JSON and JSON-LD validation shall be applied in case of +invalid @context.

+

5.13.2.5 Output +data

+

The locally unique identifier that identifies the @context in +the broker's internal storage.

+

5.13.3 List +@contexts

+

5.13.3.1 Description

+

With this operation a client can obtain a list of URLs that represent +all of the @contexts stored in the local context store of the +broker. Each URL can be used to download the corresponding +@context, and, in case the @context's kind is "Cached", it shall be the original URL the +broker downloaded the @context from.

+

In case a details flag is set to true, the client +obtains a list of JSON objects, each representing information (metadata) +about an @context currently stored by the broker. Each JSON +object contains information about the @context's original URL (if +any), its local identifier in the broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), its creation timestamp, +its expiry date, and additional optional information.

+

5.13.3.2 Use case +diagram

+

A client can list all @contexts stored within an NGSI-LD +system as shown in Figure +5.13.3.2‑1.

+
+ +
+
+Figure 5.13.3.2-1: List @contexts use case +
+

5.13.3.3 Input +data

+
    +
  • +A kind filter indicating the kind of stored @contexts that +are to be included in the output list. Currently, possible kinds are +"Cached", "Hosted" and "ImplicitlyCreated" (optional). +
    • +
  • +A boolean details flag indicating that detailed JSON objects +representing metadata about the stored @contexts instead of +simple URLs are requested (optional). +
    • +
+

5.13.3.4 Behaviour

+

The broker shall provide a URL or JSON object for each +@context currently stored in the internal broker's storage, that +match the filter. If no filter is specified, all kinds are included.

+

5.13.3.5 Output +data

+

A list of URLs, or a list of resulting JSON objects containing the +following fields:

+
    +
  • +URL; +
    • +
  • +localId; +
    • +
  • +kind; +
    • +
  • +createdAt; +
    • +
  • +expiresAt [OPTIONAL]; +
    • +
  • +lastUsage [OPTIONAL]; +
    • +
  • +numberOfHits [OPTIONAL, number of times the @context was found in the +storage]; +
    • +
  • +extraInfo [OPTIONAL, used by implementations to report any kind of +custom information]. +
    • +
+

5.13.4 Serve +@context

+

5.13.4.1 Description

+

With this operation a client can obtain the full content of a +specific @context (only for @contexts of kind "Hosted" or "ImplicitlyCreated"), which is currently stored +in the broker's internal storage, or its metadata (for all kinds of +stored @contexts).

+

5.13.4.2 Use case +diagram

+

A client can request the broker to serve a specific @context +stored within the NGSI-LD system as shown in Figure +5.13.4.2‑1.

+
+ +
+
+Figure 5.13.4.2-1: Serve @context use case +
+

5.13.4.3 Input +data

+
    +
  • +The locally unique identifier that identifies the desired +@context in the broker's internal storage. Such unique +identifiers are obtained by the client as a result of either a "Add +@context" (clause +5.13.2) API operation or of a "List @contexts" (clause +5.13.3) API operation. For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. +
    • +
  • +A boolean details flag indicating that a JSON object representing +metadata about the @context, instead of the full content, is +requested (optional). +
    • +
+

5.13.4.4 Behaviour

+
    +
  • +If details is set to false, or details is not +present, the broker shall give back the full content of the +@context that corresponds to the indicated local identifier, +serving it from its internal storage, if the @context that +corresponds to the indicated local identifier is of kind "Hosted" or "ImplicitlyGenerated". It shall give back +OperationNotSupported error if it is of kind "Cached". It shall give back +ResourceNotFound if the identifier is not found. +
    • +
  • +Otherwise, if details is set to true, the broker shall +give back metadata about the @context that corresponds to the +indicated local identifier. It shall give back ResourceNotFound +error if the identifier is not found. +
    • +
+

5.13.4.5 Output +data

+

The full content of the indicated @context (or its metadata as +specified in clause +5.13.3.5), or ResourceNotFound/OperationNotSupported +errors.

+

5.13.5 Delete +and Reload @context

+

5.13.5.1 Description

+

With this operation, a client supplies a local identifier to the +broker, indicating a stored @context, that the broker shall +remove from its storage. For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. If the entry in the local +storage that corresponds to the identifier is itself an array of +@contexts, this operation will not delete the +children, i.e. the @contexts in the array, but just the +entry.

+

5.13.5.2 Use case +diagram

+

A client can request the broker to delete (and optionally reload) a +specific @context stored within the NGSI-LD system as shown in Figure +5.13.5.2‑1.

+
+ +
+
+Figure 5.13.5.2-1: Delete and Reload @context use case +
+

5.13.5.3 Input +data

+
    +
  • +The locally unique identifier that identifies the desired +@context in the broker's internal storage. For @contexts +of kind "Cached" this can also be the +original URL the broker downloaded the @context from. +
    • +
  • +A reload boolean flag indicating that reloading of the +@context shall be attempted (optional). +
    • +
+

5.13.5.4 Behaviour

+
    +
  • +If the @context identifier is not supplied, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the @context identifier does not correspond to any existing +entry in the @context storage, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If reload is true and the kind of the @context is +"Cached", implementations shall try to +re-download the identified @context from its original URL, before +removing it from the internal storage. If downloading fails, or the +downloaded @context is invalid according to JSON and JSON-LD +validation of clause +5.5.4, then an error of type LdContextNotAvailable shall be +raised. More detailed information about the errors shall be specified in +the ProblemDetails (see IETF RFC 7807 [10]) field of the response. +In case of any error, the operation ends without removing the existing +@context. Otherwise, the existing @context is replaced +with the newly downloaded one. +
    • +
  • +If reload is true and the kind of the @context is +not "Cached", +implementations shall return a BadRequestData error. +
    • +
  • +If reload is false (or reload is not supplied), +implementations shall remove from the internal storage the +@context that corresponds to the given identifier. The local +identifier is used for finding the @contexts in the internal +broker's storage. If the local identifier is not in the storage, a +ResourceNotFound error shall be raised. +
    • +
+

5.13.5.5 Output +data

+

None.

+

5.14 Context Source Entity +Mapping

+

5.14.1 Retrieve +EntityMap

+

5.14.1.1 Description

+

With this operation a client can obtain a cached EntityMap which is +currently stored in the broker's internal storage, or memory.

+

5.14.1.2 Use case +diagram

+

A client can request the broker to retrieve a specific EntityMap +within the NGSI-LD system as shown in Figure +5.14.1.2‑1.

+
+ +
+
+Figure 5.14.1.2-1: Retrieve EntityMap +
+

5.14.1.3 Input +data

+

EntityMap ID (URI) of the EntityMap to be retrieved (target +EntityMap).

+

5.14.1.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +Otherwise, return a JSON-LD object representing the EntityMap as +mandated by clause +5.2.39. +
    • +
+

5.14.1.5 Output +data

+

A JSON-LD object representing the target EntityMap as mandated by clause +5.2.39.

+

5.14.2 Update +EntityMap

+

5.14.2.1 Description

+

This operation allows performing a partial update on an +NGSI-LD EntityMap. A partial update only changes the elements +provided in the EntityMap Fragment, leaving the rest as they are.

+

5.14.2.2 Use case +diagram

+

A client can request the broker to update an EntityMap which is +currently stored in the broker's internal storage as shown in Figure +5.14.2.2‑1.

+
+ +
+
+Figure 5.14.2.2-1: Update EntityMap +
+

5.14.2.3 Input +data

+
    +
  • +EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). +
    • +
  • +A JSON-LD document representing an EntityMap. +
    • +
+

5.14.2.4 Behaviour

+
    +
  • +If the EntityMap ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +Perform an update operation on the target EntityMap using the fields +specified within then JSON-LD document. Any provided output-only fields +shall be ignored. +
    • +
+

5.14.2.5 Output +data

+

None.

+

5.14.3 Delete +EntityMap

+

5.14.3.1 Description

+

This operation allows deleting an NGSI-LD EntityMap.

+

5.14.3.2 Use case +diagram

+

A client can request the broker to completely delete an EntityMap +held within the NGSI-LD system as shown in Figure +5.14.3.2‑1.

+
+ +
+
+Figure 5.14.3.2-1: Delete EntityMap +
+

5.14.3.3 Input +data

+

EntityMap ID (URI) of the EntityMap to be retrieved (target +EntityMap).

+

5.14.3.4 Behaviour

+
    +
  • +If the EntityMap ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +The EntityMap shall be removed from the broker's internal storage, or +memory. +
    • +
+

5.14.3.5 Output +data

+

None.

+

5.14.4 Create EntityMap for +Query Entities

+

5.14.4.1 Description

+

This operation is very similar to the Query Entities operation in clause +5.7.2, except that it does not directly return Entities, but creates +and returns an Entity map including the identifiers of the Entities that +are candidates to be part of the query results. The Entity map can then +be used for paginating through the included Entities.

+

5.14.4.2 Use case +diagram

+

A Context Consumer can retrieve an Entity map with the +Entities that match a specific query from an NGSI-LD system as shown in +Figure +5.14.4.2‑1.

+
+ +
+
+Figure 5.14.4.2-1: Query Entities for creating EntityMap use case +
+

5.14.4.3 Input data

+
+To simplify the operation, the same parameters as for the Query Entities +operation (clause +5.7.2) are allowed, but some of these are irrelevant for creating an +Entity map and thus shall be ignored. +
+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type names (short hand string) and fully qualified type names (URI) +are allowed in the selector. +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope" or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list member names ("id", "type", "scope" or an Attribute +name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +In the case of GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (ignored). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (ignored). +
    • +
+
    +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context +Sources by the values of properties that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9 (ignored). +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +An optional flag indicating whether to include additional Linked +Entities corresponding to the Relationships retrieved and how to +format those Linked Entities. See clause +4.5.23 (optional). +
    • +
  • +A limit to the depth of Linked Entities to search whilst traversing an +Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A list (one or more) of Linked Entity identifiers previously encountered +whilst traversing an Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (ignored, EntityMap is always +returned). +
    • +

  • A suggested expiry time for the EntityMap (optional).

    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (ignored). +
    • +
  • +A datasetId parameter that specifies which Attribute instances +are to be selected as defined by clause +4.5.5 (optional). +
    • +
  • +A flag indicating whether split Entities are to be expected, i.e. +Entities whose information is distributed across different Context +Sources (optional). +
    • +
+

In the general case, it is not possible to retrieve a set of entities +by only specifying desired Entity identifiers, without further +specifying restrictions on the Entities' types or attributes, either +explicitly, via selector of Entity types or of Attribute names, or +implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the +operation is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided.

+

5.14.4.4 Behaviour

+
    +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause +5.5.13). +
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked +Entity retrieval, and the use of Linked Entity retrieval is not +specified, or the projected attribute depth exceeds the Linked Entity +retrieval depth, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the filter conditions specified by the query includes Linked Entity +attributes, and the use of Linked Entity retrieval is not specified, or +the Linked Entity attribute query depth exceeds the Linked Entity +retrieval depth, an error of type BadRequestData shall be raised +(too deep query). +
    • +
  • +If geometryProperty parameter is present and the Accept Header is not +set to "application/geo+json", then an error of type +BadRequestData shall be raised. +
    • +
  • +Otherwise, +
    +
      +
    • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
      • +
    • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
      • +
    • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, and +local scope is not specified, implementations shall run a query that +shall return an EntityMap containing the identifiers of all the Entities +found locally that meet all of the following conditions: +
      +
        +
      • +id is equal to any of the id(s) passed as a parameter; +
        • +
      • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
        • +
      • +id matches the id pattern passed as a parameter. +
        • +
      • +
    • +Otherwise, implementations shall run a query that shall return an +EntityMap containing the identifiers pf all Entities found locally that +meet all of the following conditions (given the respective parameter is +provided): +
      +
        +
      • +id is equal to any of the id(s) passed as a parameter; +
        • +
      • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
        • +
      • +Attribute matches any of the expanded attribute(s) in the list that is +passed as a parameter; +
        • +
      • +id matches the id pattern passed as a parameter; +
        • +
      • +the filter conditions specified by the query are met (as mandated by clause +4.9); +
        • +
      • +the geospatial restrictions imposed by the geoquery are met (as mandated +by clause +4.10); if there are multiple instances of the GeoProperty on which +the geoquery is based, it is sufficient if any of these instances meets +the geospatial restrictions; +
        • +
      • +if the Scope query is present, it shall match a present Entity Scope (as +mandated by clause +4.19, for an example see annex +C, clause +C.5.15); +
        • +
      • +if the Attribute list is present, in order for an Entity to match, it +shall contain at least one of the Attributes in the projection Attribute +list. +
        • +
      • +
    • +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source Registrations that match the query and +support the "createEntityMapQueryEntity" operation (see operations and +operation groups in clause +4.20), implementations shall do the following: +
    +
      +
    • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, the +filters (filter conditions specified by the query, geospatial +restrictions imposed by the geoquery, Scope query, Attributes) shall be +removed before forwarding the request. +
      • +
    • +For each matching Context Source Registration, the request is forwarded +for remote querying by matching endpoints. The result of each remote +query is an EntityMap. The mapping between the Context Source +Registration and the EntityMap Id is added to the linkedMaps +element of the local EntityMap and for the Entity ids included in the +returned EntityMaps a mapping to the Context Source Registration is +added to the entityMap element of the local EntityMap. +
      • +
    • +
+
    +
  • +The local EntityMap is stored and made accessible based on its +identifier. +
    • +
+

5.14.4.5 Output data

+

The location of the local EntityMap shall be returned in a specific +field in the response, as well as the EntityMap itself.

+

5.14.5 +Create EntityMap for Query Temporal Evolution of Entities

+

5.14.5.1 Description

+

This operation is very similar to the Query Temporal Evolution of +Entities operation in clause +5.7.4, except that it does not directly return the Temporal +Evolution of Entities but creates and returns an Entity map including +the identifiers of the Entities that are candidates to be part of the +query results. The Entity map can then be used for paginating through +Temporal Evolution of the included Entities.

+

5.14.5.2 Use case +diagram

+

A Context Consumer can retrieve an Entity map with the +Temporal Evolution of a set of Entities which matches a specific query +from an NGSI-LD system as shown in Figure +5.14.5.2‑1.

+
+ +
+
+Figure 5.14.5.2-1: Query Temporal Evolution for creating EntityMap use +case +
+

5.14.5.3 Input data

+

To simplify the operation, the same parameters as for the Query +Temporal Evolution of Entities operation (clause +5.7.4) are allowed, but some of these are irrelevant for creating an +Entity map and thus will be ignored.

+
    +
  • +An NGSI-LD temporal query as mandated by clause +4.11. +
    • +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type name (short hand string) and fully qualified type name (URI) +are allowed. +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope" or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", "scope" or an +Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context +Sources by the values of properties that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9 (ignored). +
    • +
  • +A parameter (lastN) conveying that only the last N instances (per +Attribute) within the concerned temporal interval shall be retrieved +(optional). +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (ignored, EntityMap is always +returned). +
    • +

  • A suggested expiry time for the EntityMap (optional).

    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (ignored). +
    • +
  • +A datasetId parameter that specifies which Attribute instances are to be +selected as defined by clause +4.5.5 (optional). +
    • +

  • A flag indicating whether split Entities are to be expected, i.e. +Entities whose information is distributed across different Context +Sources (optional).

    • +
  • +In the general case, it is not possible to retrieve a set of entities by +only specifying desired Entity identifiers, without further specifying +restrictions on the entities' types or attributes, either explicitly, +via selector of Entity types or of Attribute names, or implicitly, +within an NGSI-LD query or geoquery. If the execution of the operation +is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided. +
    • +
+

5.14.5.4 Behaviour

+
    +
  • +If a temporal query is not provided then an error of type +BadRequestData shall be raised. +
    • +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause +5.5.13). +
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If projection attributes or filter conditions indicate the use of Linked +Entity retrieval, an error of type BadRequestData shall be +raised. +
    • +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be observed +mandated by clause +5.5.7. +
    • +
  • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
    • +
  • +The lastN parameter refers to a number, n, of Attribute +instances which shall correspond to the last n timestamps (in +descending ordering) of the temporal property (by default +observedAt) within the concerned temporal interval. +
    • +
  • +Otherwise, +
    • +
+
    +
  • +Let S be the set of selected Entities i.e. the query result set. +
    • +
  • +If the split entities flag is explicitly set to true or, if not +explicitly set, the default setting of the deployment allows split +entities, and local scope is not specified, implementations shall run a +query so that the result set contains all the Entities found locally, +that meet all of the following conditions (given the +respective parameter is provided): +
    +
      +
    • +If id(s) is provided, keep in S only those Entities whose id is +equivalent to any of the id(s) passed as a parameter. +
      • +
    • +If an id pattern is provided, keep in S only those Entities whose id +matches the id pattern. +
      • +
    • +If a selector of Entity Types is provided, keep in S only those Entities +whose Entity Type names match the selector of Entity Types. +
      • +
    • +From S, select only those Entities any of whose Attribute instances +(corresponding to the Attributes specified by the query or all if none +are specified) match the temporal restrictions imposed by the temporal +query (as mandated by clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S4 be this new subset. +
      • +
    +
      +
    • +Otherwise implementations shall run a query that shall return the set of +matching Entities (all Entities stored locally, in case only a local +scope is specified); the logical steps to select the final result set of +Entities, and the Attribute instances included as part of their temporal +representation, are enumerated as follows: +
      +
        +
      • +If id(s) is provided, keep in S only those Entities whose id is +equivalent to any of the id(s) passed as a parameter. +
        • +
      • +If an id pattern is provided, keep in S only those Entities whose id +matches the id pattern. +
        • +
      • +If a selector of Entity Types is provided, keep in S only those Entities +whose Entity Type names match the selector of Entity Types. +
        • +
      • +From S, select only those Entities any of whose Attribute instances +(corresponding to the Attributes specified by the query or all if none +are specified) match the temporal restrictions imposed by the temporal +query (as mandated by clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S1 be this new subset. +
        • +
      • +If a values filter query is provided, from S1, select those Entities +whose Attribute instances (during the interval defined by the temporal +query) meet the matching conditions specified by the query (as mandated +by clause +4.9); i.e. the values filter query shall be checked against all the +Attribute instances resulting from the initial filtering performed by +the temporal query. Let S2 be this new subset. +
        • +
      • +If no values filter query is provided, then S2 is equal to S1. +
        • +
      • +If geoquery is present, from S2, select those Entities whose +GeoProperty instances meet the geospatial restrictions imposed by +the geoquery (as mandated by clause +4.10); those geospatial restrictions shall be checked against the +GeoProperty instances that are within the interval defined by the +temporal query. Let S3 be this new subset. +
        • +
      • +If no geoquery is provided, then S3 is equal to S2. +
        • +
      • +If the Scope query is present, from S3, select those Entities whose +Entity Scope instances match the Scope query (as mandated by clause +4.19, for an example see annex +C, clause +C.5.16). Let S4 be the new subset. +
        • +
      • +If no Scope query is provided, then S4 is equal to S3. +
        • +
      • +
    • +The local EntityMap is created based on S4. +
      • +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source Registrations that match the query and +support the "createEntityMapQueryTemporal" operation (see operations and +operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If split entities flag is explicitly set to true or, if not explicitly +set, the default setting of the deployment allows split entities, the +filters (filter conditions specified by the query, geospatial +restrictions imposed by the geoquery, Scope query, Attributes) shall be +removed before forwarding the request. +
    +
    + +
    • +

  • For each matching Context Source Registration, the request is +forwarded for remote querying by matching endpoints. The result of each +remote query is an EntityMap. The mapping between the Context Source +Registration and the EntityMap Id is added to the linkedMaps +element of the local EntityMap and for the Entity ids included in the +returned Entity Maps a mapping to the Context Source Registration is +added to the entityMap element of the local EntityMap.

    • +
+
    +
  • +The local EntityMap is stored and made accessible based on its +identifier. +
    • +
+

5.7.4.5 Output Data

+
+The location of the local EntityMap shall be returned in a specific +field in the response, as well as the EntityMap itself. +
+

5.15 Context Source Identity +Information

+

5.15.1 Retrieve +Context Source Identity Information

+

5.15.1.1 Description

+

With this operation, a client can obtain Context Source identity information which +uniquely defines the Context Source +itself. In the multi-tenancy use case (see clause +4.14), a client can obtain identify information about a specific +Tenant within a Context Source.

+

5.15.1.2 Use case +diagram

+

A client can request the broker to retrieve identity information about a specific +Context Source within the NGSI-LD +system as shown in Figure +5.15.1.2‑1.

+
+ +
+
+Figure 5.15.1.2-1: Retrieve Context Source Identity Information +
+

5.15.1.3 Input +data

+

None.

+

5.15.1.4 Behaviour

+
    +
  • +If the Context Source is unable to +supply identity information about itself, then error of type +NotImplemented shall be raised. +
    • +
  • +Return a JSON-LD object representing the identity of the Context Source itself as mandated by clause +5.2.40. This can also include additional configurational data +dependent on the specificContext +Source implementation. +
    • +
+

5.14.1.5 Output +data

+

A JSON-LD object representing the identity of the Context Source as mandated by clause +5.2.40.

+ + diff --git a/public/10-tabcontext-information-management-framework.html b/public/10-tabcontext-information-management-framework.html new file mode 100644 index 0000000000000000000000000000000000000000..ba145496b2b2fc65447b73d316812b13e97b2f14 --- /dev/null +++ b/public/10-tabcontext-information-management-framework.html @@ -0,0 +1,12645 @@ + + + + + + + 4 Context Information Management Framework + + + + + + + +
+

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.

+
+ +
+
+Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure +
+

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.

+
+ +
+
+Legend: +
+
+ +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+[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.2-1: NGSI-LD Core Meta-Model +
+

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

+
+ +
+
+Legend: +
+
+ +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+[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: NGSI-LD Core Meta-Model plus the Cross-Domain 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".

+
+ +
+
+Figure 4.2.4-1: Cross-Domain Ontology and instantiation +
+

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.

+
+ +
+
+Figure 4.2.5-1: NGSI-LD information model as UML +
+

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 NGSI-LD API implicitly defines two sets of Entities: +
+
    +
  • +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.

+
+ +
+
+Figure 4.3.2-1: Centralized architecture +
+

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.

+
+ +
+
+Figure 4.3.3-1: Distributed architecture +
+

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.

+
+ +
+
+Figure 4.3.4-1: Federated architecture +
+

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.

+
+Table 4.3.5-1: NGSI-LD API structure +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+API +
+Functionality +
+Operations +
+Core API +
+Context Information Provision - operations for providing or managing +Entities and Attributes +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
Context Information Consumption +- operations for consuming Entities and checking for which Entity Types +and Attributes Entities are available in the system
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
Context Information Subscription +- operations for subscribing to Entities, receiving notifications and +managing subscriptions
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+
+5.8.6 Notification +
+Temporal API +
Temporal Context Information +Provision - operations for providing or managing the Temporal Evolution of +Entitiesand +Attributes
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
Temporal Context Information +Consumption - operations for consuming the Temporal Evolution of +Entities
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
+Registry API +
Context Source +Registration- +operations for registering Context Sourcesand managing Context Source +Registrations(CSRs)
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
Context SourceDiscovery - operations for +retrieving and discovering CSRs
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
Context Source +RegistrationSubscription - operations for +subscribing to CSRs, receiving notifications and managing +CSRs
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+
+5.11.7 CSR Notification +
JSONLDContext APIStoring, managing and serving +@contexts
+5.13.2 Add @context +
+
+5.13.3 List @contexts +
+
+5.13.4 Serve @context +
+
+5.13.5 Delete and Reload @context +
+

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-2: Main implementation configurations +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Description +
+Temporal API +
+Registry API +
+Central Broker without temporal support +
+none +
+none +
+Central Broker with integrated temporal component +
+local +
+none +
+Central Broker with separate temporal component +
+separate +
+none +
+Context Broker supporting distributed and federated deployments without +temporal support and with integrated Context Registry +
+none +
+local +
+Context Broker supporting distributed and federated deployments with +integrated temporal component and integrated Context Registry +
+local +
+local +
+Context Broker supporting distributed and federated deployments with +separate temporal component and integrated Context Registry +
+separate +
+local +
+Context Broker supporting distributed and federated deployments without +temporal support and separate Context Registry +
+none +
+separate +
+Context Broker supporting distributed and federated deployments with +integrated temporal component and separate Context Registry +
+local +
+separate +
+Context Broker supporting distributed and federated deployments with +separate temporal component and separate Context Registry +
+separate +
+separate +
+

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.

+
+Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+NGSI-LD Role +
+Implements +
+Uses +
+Context Consumer +
+5.8.6 Notification - if supporting asynchronous +interactions +
+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.11.7 CSR Notification - if supporting asynchronous +interactions +
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
+
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+ if supporting asynchronous interactions: +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+Context Producer +
+none +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
+Context Source +
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
+
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+5.8.6 Notification +
+
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+Context Repository +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
+none +
+Temporal Context Consumer +
+In case of direct interactions with Context Registry: +
+
+5.11.7 CSR Notification - if supporting asynchronous +interactions +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+ +
+
+if supporting asynchronous interactions: +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+Temporal Context Producer +
+None +
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
+Temporal Context Source +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+Temporal Context Repository +
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
+none +
+Context Registry +
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+5.11.7 CSR Notification +
+

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 be fully +specified and always relates 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 redirect Context Source +Registration also specifies that the registered context data is +held in a location external to the Context +Broker. It is possible to register (any combination of): +
+
    +

  • 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 +[27])) 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

+
+If the optional array (of KeyValuePair type, as defined by clause +5.2.22) contextSourceInfo of the CSourceRegistration is +present, it contains, whatever extra information the Context Broker shall convey when contacting +the Context Source. This can be +information the Context Broker needs +to successfully communicate with the Context +Source (e.g. Authorization material), or for the Context Source to correctly interpret the +received content (e.g. the Link URL to fetch an @context). The +method for conveying this information is binding-specific, e.g. using +headers in the case of HTTP. +
+
+Instead of providing the actual value, the special value "urn:ngsi-ld:request" can be used to indicate +that the respective value is to be taken from the request that triggered +the given request, if present. +
+
+EXAMPLE: If the key value pair "user": "urn:ngsi-ld:request" +is part of contextSourceInfo of the CSourceRegistration, +the Context Broker checks if "user" was conveyed in the triggering request. +If this is the case, e.g. "user": "abcd", "user": "abcd" is also conveyed when contacting the +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

+
+The following key-values have a specific well-defined meaning when +defined as elements within the optional array contextSourceInfo +of the CSourceRegistration. +
+
    +
  • +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. +
    • +
+
+NOTE 1: In the following, the term Attribute is used when referring in +the text to both a Property and a Relationship (see definition of +NGSI-LD Attribute in clause +3.1). +
+
+NOTE 2: When GeoJSON representation is selected, the layout of the +Entities changes, see clause +4.5.16 for details. +
+

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).
    +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. +
      +
      +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). +
      +
      +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).
    +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. +
      +
      +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). +
      +
      +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. +
    • +
+
+EXAMPLE 1: "name": "David Robert Jones" +
+
    +
  • +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 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". +
    • +
+
+
+EXAMPLE 2: +
+
+"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: +
+
+
+"devices": [ +
+
+     "urn:ngsi-ld:Device:14142", +
+
+     "urn:ngsi-ld:Device:13562",  +
+
+     "urn:ngsi-ld:Device:37309" +
+
+] +
+
    +
  • +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: +
+
+
+"providedBy": { +
+
+  "id": "urn:ngsi-ld:Device:31415", +
+
+  "type": "Device", +
+
+  "brandName": "Anemometer", +
+
+  "manufacturerName": "Cyberdyne Systems", +
+
+  "windSpeed": 60 +
+
+}
+ +
+
+
+EXAMPLE 10: +
+
+
+"devices": [ +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:14142", +
+
+       "type": "Device", +
+
+       "brandName": "Anemometer", +
+
+       "manufacturerName": "Cyberdyne Systems", +
+

          "windSpeed": 60

+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:13562", +
+
+       "type": "Device", +
+
+       "brandName": "Hygromometer", +
+
+       "manufacturerName": "Acme Corporation", +
+
+       "humidity": 64 +
+
+    }, +
+
+    {  +
+
+       "id": "urn:ngsi-ld:Device:37309", +
+
+       "type": "Device", +
+
+       "brandName": "Barometer", +
+
+       "manufacturerName": "Trask Industries", +
+
+       "pressure": 760 +
+
+    } +
+
+] +
+
    +
  • +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: +
+
+
+[ +
+
+  { +
+
+… etc +
+
+"providedBy": "urn:ngsi-ld:Device:31415" +
+
+  }, +
+

     {

+
+  "id": "urn:ngsi-ld:Device:31415", +
+
+  "type": "Device", +
+
+  "brandName": "Anemometer", +
+
+  "manufacturerName": "Cyberdyne Systems", +
+
+  "windSpeed": 60 +
+

     }

+
+]
+ +
+
+
+EXAMPLE 12: +
+
+
+[ +
+
+    { +
+
+      … etc +
+
+      "providedBy": [ +
+
+       "urn:ngsi-ld:Device:14142",  +
+
+         "urn:ngsi-ld:Device:13562",  +
+
+         "urn:ngsi-ld:Device:37309" +
+
+       ] +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:14142", +
+
+       "type": "Device", +
+
+       "brandName": "Anemometer", +
+
+       "manufacturerName": "Cyberdyne Systems", +
+
+       "windSpeed": 60 +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:13562", +
+
+       "type": "Device", +
+
+       "brandName": "Hygromometer", +
+
+       "manufacturerName": "Acme Corporation", +
+
+       "humidity": 64 +
+
+    }, +
+
+    {  +
+
+       "id": "urn:ngsi-ld:Device:37309", +
+
+       "type": "Device", +
+
+       "brandName": "Barometer", +
+
+       "manufacturerName": "Trask Industries", +
+
+       "pressure": 760 +
+
+    } +
+
+] +
+
+ +
+
    +
  • +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 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. +
    • +
+
+EXAMPLE 14: "periods": ["First", "Second", "Third", "Fourth"] +
+
    +
  • +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 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). +
    • +
+
+EXAMPLE 16: +
+
+ "route": [ +
+
+
+"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. +
    • +
+
+EXAMPLE 17: +
+
+"route": [ +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0101", +
+
+    "type": "BusStop", +
+
+    "stopName": "High Street", +
+
+    "location": {"type": Point, coordinates [54.112,0.334]}} +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0102", +
+
+    "type": "BusStop", +
+
+    "stopName": "Station Road",  +
+
+    "location": {"type": Point, coordinates [54.101,0.302]}} +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:9912", +
+
+    "type": "BusStop", +
+
+    "stopName": "Mornington Cresent",  +
+
+    "location": {"type": Point, coordinates [54.142,0.332]} +
+
+  } +
+
+] +
+
    +
  • +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 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. +
    • +
+
+EXAMPLE 18: +
+
+[ +
+
+  { +
+
+... etc +
+
+
+"route": [ +
+
+

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

+

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

+

         "urn:ngsi-ld:BusStop:9912"

+
+] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0101" +
+
+  "type": "BusStop", +
+

       "stopName": "High Street", 

+

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

+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0102", +
+
+  "type": "BusStop", +
+

       "stopName": "Station Road", 

+

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

+
+  }, +
+
+  { +
+

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

+
+  "type": "BusStop", +
+

       "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 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" +
+
+    ] +
+
+  } +
+
+} +
+
+ +
+
+
+NOTE: When the simplified GeoJSON representation is selected, the layout +of the Entities changes, see clause +4.5.17 for details. +
+

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 [i.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 [i.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" +
+
+    ] +
+
+  ] +
+
+} +
+
+
+EXAMPLE 7: +
+
+
+"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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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: +
    • +
+
+1) the value obtained after applying the aggregation method over the +period; +
+
+2) the start DateTime of the corresponding period; +
+
+3) the end DateTime of the corresponding period. +
+
    +
  • +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: +
    • +
+
+1) the value obtained after applying the aggregation method over the +period; +
+
+2) the start DateTime of the corresponding period; +
+
+3) the end DateTime of the corresponding period. +
+

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:

+
+Table 4.5.19.1-1: Semantics of aggregation methods for Properties on +JSON native data types +
+ ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+JSON String +
+JSON Number +
+JSON Object +
+JSON Array +
+JSON Boolean +
+
+(for the purpose of the aggregation, true is considered as a +value of 1, false is considered as a value of 0) +
+totalCount +
+Calculate the number of times the value has been updated inside the +period +
+distinctCount +
+Calculate the count of distinct values inside the period +
+sum +
+N/A +
+Calculate the sum of the values inside the period +
+N/A +
+Calculate the sum of the sizes of the arrays inside the period +
+Calculate the sum of the values inside the period +
+avg +
+N/A +
+Calculate the average of the values inside the period +
+N/A +
+Calculate the average number of the sizes of the arrays inside the +period +
+Calculate the average of the values inside the period +
+min +
+Calculate the first value in lexicographical order inside the period +
+Calculate the minimum value inside the period +
+N/A +
+Calculate the minimum size of the arrays inside the period +
+Calculate the minimum value inside the period +
+max +
+Calculate the last value in lexicographical order inside the period +
+Calculate the maximum value inside the period +
+N/A +
+Calculate the maximum size of the arrays inside the period +
+Calculate the maximum value inside the period +
+stddev +
+N/A +
+Calculate the standard deviation of the values inside the period +
+N/A +
+N/A +
+Calculate the standard deviation of the values inside the period +
+sumsq +
+N/A +
+Calculate the sum of the square of the values inside the period +
+N/A +
+N/A +
+Calculate the sum of the square of the values inside the period +
+
+Table 4.5.19.1-2: Semantics of aggregation methods for Properties on +other supported data types +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+DateTime +
+Date +
+Time +
+URI +
+totalCount +
+Calculate the number of times the value has been updated inside the +period +
+distinctCount +
+Calculate the count of distinct values inside the period +
+sum +
+N/A +
+N/A +
+N/A +
+N/A +
+avg +
+N/A +
+N/A +
+Calculate the average time inside the period (e.g. to apply on an event +that occurs at non fixed times, like the time a car enters a given +parking) +
+N/A +
+min +
+Calculate the minimum value inside the period +
+Calculate the minimum value inside the period +
+Calculate the minimum value inside the period +
+N/A +
+max +
+Calculate the maximum value inside the period +
+Calculate the maximum value inside the period +
+Calculate the maximum value inside the period +
+N/A +
+stddev +
+N/A +
+N/A +
+N/A +
+N/A +
+sumsq +
+N/A +
+N/A +
+N/A +
+N/A +
+
+Table 4.5.19.1-3: Semantics of aggregation methods for Relationships +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+Relationship +
+totalCount +
+Calculate the number of times the relationship has been updated inside +the period +
+distinctCount +
+Calculate the count of distinct relationships targets inside the period +
+sum +
+N/A +
+avg +
+N/A +
+min +
+N/A +
+max +
+N/A +
+stddev +
+N/A +
+sumsq +
+N/A +
+

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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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.

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

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:

+
+Prohibited +
+
    +
  • +"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:

+
+Prohibited +
+
    +
  • +"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:

+
+nameChar = unicodeNumber / unicodeLetter +
+
+nameChar =/ %x5F          ; _ +
+
+name = unicodeLetter *nameChar +
+
+ +
+
    +
  • +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:

+
+prefix = unicodeLetter *nameChar +
+
+name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name +
+
+ +
+

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. +
    • +
+
+NOTE 1: In previous versions of NGSI-LD, only the comma was supported as +ISO 8601 [17] states +that it is the preferred option. However, in practice the decimal point +is more commonly used. +
+
    +
  • +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. +
    • +
+
+NOTE 2: In previous versions of NGSI-LD, only the comma was supported as +ISO 8601 [17] states +that it is the preferred option. However, in practice the decimal point +is more commonly used. +
+
    +
  • +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.

+
+NOTE 1: For simplicity reasons, a TemporalProperty is represented +only by its Value, i.e. no Properties of TemporalProperty +nor Relationships of TemporalProperty can be conveyed. In +more formal language, a TemporalProperty does not allow +reification. +
+
+NOTE 2: It is important to remark that the term TemporalProperty +has been reserved for the semantic tagging of non-reified structural +timestamps (observedAt, createdAt, +modifiedAt, deletedAt), which capture the temporal evolution of +Attributes. Only such structural timestamps can be used +as timeproperty in Temporal Queries as mandated +by clause +4.11. +
+
+NOTE 3: User-defined Properties whose value is a time value +(Date, DateTime or Time) are defined as Property, not as +TemporalProperty, and are serialized in NGSI-LD as shown in annex +C, clause +C.6. +
+
+NOTE 4: Whenever a TemporalProperty value is unknown by a +registered Context Source, the +Property shall be omitted rather than sending an error response. +
+

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:

+
+Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm / +QueryTermAssoc)) +
+
+QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ; +(QueryTerm) +
+
+QueryTerm = Attribute +
+
+QueryTerm =/ Attribute Operator ComparableValue +
+
+QueryTerm =/ Attribute equal CompEqualityValue +
+
+QueryTerm =/ Attribute unequal CompEqualityValue +
+
+QueryTerm =/ Attribute patternOp RegExp +
+
+QueryTerm =/ Attribute notPatternOp RegExp +
+
+Attribute = LinkedEntityRelation +
+
+LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D ; +AttrName{LinkedEntityPath} +
+
+LinkedEntityRelation =/ ValuePath +
+
+LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B +LinkedEntityPath %x7D +
+
+;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath} +
+
+LinkedEntityPath =/ ValuePath +
+
+ValuePath = DottedPath *1(%x5B DottedPath %x5D) ; DottedPath +*1([DottedPath]) +
+
+DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName) +
+
+Operator = equal / unequal / greaterEq / greater / lessEq / less +
+
+ComparableValue = Number / quotedStr / dateTime / date / time +
+
+OtherValue = false / true +
+
+Value = ComparableValue / OtherValue +
+
+Range = ComparableValue dots ComparableValue +
+
+ValueList = Value 1*(%x2C Value) ; Value 1*(, Value) +
+
+CompEqualityValue = OtherValue / ValueList / Range / URI +
+
+equal = %x3D %x3D ; == +
+
+unequal = %x21 %x3D ; != +
+
+greater = %x3E ; > +
+
+greaterEq = %x3E %x3D ; >= +
+
+less = %x3C ; < +
+
+lessEq = %x3C %x3D ; <= +
+
+patternOp = %x7E %x3D ; ~= +
+
+notPatternOp = %x21 %x7E %x3D ; !~= +
+
+dots = %x2E %x2E ; .. +
+
+TermChar = unicodeNumber / unicodeLetter +
+
+TermChar =/ %x5F ; _ +
+
+AttrName = unicodeLetter *TermChar +
+
+EntityType = unicodeLetter *TermChar +
+
+quotedStr = String ; "*char" +
+
+andOp = %x3B ; ; +
+
+orOp = %x7C ; | +
+
+LogicalOp = andOp / orOp +
+
+ +
+
    +
  • +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.

+
+EXAMPLE 0: ?q=temperature. (checks for the existence of the +attribute temperature) +
+
+EXAMPLE 1: ?q=temperature==20 +
+
+EXAMPLE 2: ?q=brandName!="Mercedes" +
+
+EXAMPLE 3: ?q=isParked=="urn:ngsi-ld:OffStreetParking:Downtown1" +
+
+EXAMPLE 4: A query encoded as an HTTP Query String. Note that this is +HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2. The +NGSI-LD query language string is conveyed by means of parameter +q +
+
+ ?q=speed>50;brandName!="Mercedes". +Also note that (as stated above) URI-encoding (percent-encoding) is +required if the query string contains reserved characters (see IETF RFC +3986 [5] and IETF RFC +3987 [23], for the +exact list of them) +
+
+EXAMPLE 5: ?q=isMonitoredBy (to query Entities that have the +Attribute isMonitoredBy) +
+

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.

+
+EXAMPLE 6: ?q=((speed>50|rpm>3000);brandName=="Mercedes") +
+
+EXAMPLE 7: ?q=(temperature>=20;temperature<=25)|capacity<=10 +
+

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. +
    • +
+
+EXAMPLE 8: ?q=temperature.observedAt>=2017-12-24T12:00:00Z +
+

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.

+
+EXAMPLE 9: ?q=address[city]=="Berlin". The trailing path is +[city]. It is used to refer to a +particular subitem within the value of the address +Property, which is a complex JSON object representing a postal +address. Refer to the following NGSI-LD Entity: +
+
+{ +
+
+  "id": "urn:ngsi-ld:placedescription:123", +
+
+  "type": "PlaceDescription", +
+
+  "address": { +
+
+    "type": "Property", +
+
+    "value": { +
+
+      "city": "Berlin", +
+
+      "street": "Ulrich Strasse" +
+
+    } +
+
+  } +
+
+} +
+
+
+ +
+
+
+EXAMPLE 10: ?q=sensor.rawdata[airquality.particulate]==40. The +trailing path is [airquality.particulate]. The +particulate Property of the compound JSON object is targeted. +Refer to the following NGSI-LD Entity: +
+
+{ +
+
+  "id": "urn:ngsi-ld:particulatemeasurement:345", +
+
+  "type": "ParticulateMeasurement", +
+
+  "sensor": { +
+
+    "type": "Property", +
+
+    "value": 40, +
+
+    "rawdata": { +
+
+      "type": "Property", +
+
+      "value": { +
+
+        "airquality": { +
+
+          "particulate": 40, +
+
+          "PM20": 85 +
+
+        } +
+
+      } +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+EXAMPLE 11: ?q=parkingTickets[value]=="Overstay 60 minutes"&jsonKeys=parkingTickets. The trailing path is parkingTickets. The parkingTicketsProperty of the JSON +object is targeted, but the target value +raw is JSON, and is not expanded to ngsi-ld:hasValue using the core +@context. Refer to the following NGSI-LD Entity: +
+
+{ +
+
+  "id": "urn:ngsi-ld:Car:6152s", +
+
+  "type": "Car", +
+
+  "parkingTickets": { +
+
+  "type": "JsonProperty", +
+
+  "json": { +
+
+         "id": "85a6cc52-0589-45f9", +
+
+         "value": "Overstay 60 minutes" +
+
+      } +
+
+  } +
+
+} +
+
+ +
+
+EXAMPLE 12: ?q=gender==Male&expandValues=gender. The trailing path is gender. The gender Property of +JSON object is targeted, but the target value is first expanded to a URI +using the supplied @context. Refer to the following NGSI-LD +Entity: +
+
+{ +
+
+  "id": "urn:ngsi-ld:Person:678", +
+
+  "type": "Person", +
+
+  "gender": { +
+
+    "type": "VocabProperty", +
+
+    "vocab": "Male", +
+
+    } +
+
+  }, +
+
+  @context": { +
+
+  "Male": "http://example.org/Male", +
+
+  } +
+
+} +
+

The filter can also apply to a Property or Relationship +of an NGSI-LD Entity targeted by a (recursively) followed +Relationship, for example as part of a linked entity retrieval (clause +4.5.23).

+
+
+ +
+
+
+EXAMPLE 13: ?q=sensor{humidity}==40. The +trailing path is sensor{humidity}. The query targets entities with a +sensor Relationship and makes a sub-query on matching +target objects which have the matching humidity Attribute. Refer +to the following NGSI-LD Entities: +
+
+{ +
+
+  "id": "urn:ngsi-ld:WeatherStation:123", +
+
+  "type": "WeatherStation", +
+
+  "sensor": { +
+
+    "type": "Relationship", +
+
+  "objectType": "Device", +
+
+    "object": "urn:ngsi-ld:Device:345" +
+
+  } +
+
+} +
+
+ +
+
+{ +
+
+  "id": "urn:ngsi-ld:Device:345", +
+
+  "type": "Device", +
+
+  "humidity": { +
+
+    "type": "Property", +
+
+    "value": 40 +
+
+  } +
+
+} +
+

As not knowing the Entity Type targeted by a Relationship +could make the query significantly more expensive, a hint for the +required Entity Type can be provided, so only such NGSI-LD Entities need +to be considered.

+
+
+ +
+
+
+EXAMPLE 14: ?q=sensor{Device:humidity}==40. The trailing +path is sensor{Device:humidity}. The query targets entities +with a sensor.entityType = +"Device" within a Relationship and then +makes a sub-query on matching target objects which have the +matching humidity Attribute. The entityType hint results +in a faster lookup. Refer to the following NGSI-LD Entities. +
+
+{ +
+
+  "id": "urn:ngsi-ld:WeatherStation:123", +
+
+  "type": "WeatherStation", +
+
+  "sensor": { +
+
+    "type": "Relationship", +
+
+  "objectType": "Device", +
+
+    "object": "urn:ngsi-ld:Device:345" +
+
+  } +
+
+} +
+
+ +
+
+{ +
+
+  "id": "urn:ngsi-ld:Device:345", +
+
+  "type": "Device", +
+
+  "humidity": { +
+
+    "type": "Property", +
+
+    "value": 40 +
+
+  } +
+
+} +
+
+ +
+

If the target element corresponds to a Relationship or +ListRelationship, the combination of such target element with any +operator different than equal or unequal shall result in +not matching.

+

A Query Term value shall be any of the following +(depending on the operator used):

+
    +
  • +A literal value (string, number, date, etc.) (production rule named +Value). +
    • +
  • +A range of values (production rule named Range), specified +as a minimum and a maximum value. +
    • +
  • +A regular expression (production rule named RegExp). +
    • +
  • +A URI (production rule named URI). +
    • +
  • +A comma-separated list of literal values (production rule named ValueList). +
    • +
+

When comparing dates or times, the order relation considered shall be +a temporal one.

+

When it comes to comparing text strings, implementations:

+
    +
  • +shall follow the recommendations defined by IETF RFC 8259 [6], section 8.3. +
    • +
  • +should support the Unicode Collation Algorithm (UCA), as defined by +[13]. +
    • +
+

URI comparison should be performed so that the number of false +negatives is minimized, as recommended by IETF RFC 3986 [5], section 6.

+

The semantics of the different logical operators used by Query Terms +are described as follows and shall be supported by compliant +implementations:

+
    +
  • +Existence (only attribute is specified). A matching +entity shall contain the target element. +
    • +
  • +Equal operator (production rule named equal). A matching +Entity shall contain the target element and meet any of the following +conditions: +
    • +
+
    +
  • +The Query Term value, e.g. color=="red": +
    • +
+
    +
  • +Is identical or equivalent to the target value (e.g. matches "red"). +
    • +
  • +Is included in the target value, if the latter is an array (e.g. matches +["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a list of values (production rule named ValueList), e.g. +color=="black", "red": +
    • +
+
    +
  • +The target value is identical or equivalent to any of the list values +(e.g. matches "red"). +
    • +
  • +The target value includes any of the Query Term values, if the target +value is an array (e.g. matches ["red","blue"]). +
    • +
+
    +
  • +If the Query Term value is a range (production rule named Range), e.g. temperature==10..20: +
    • +
+
    +
  • +The target value is in the interval between the minimum and maximum of +the range (both included) (e.g. matches 15). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and a natural language is specified e.g. color[en]=="red": +
    +
      +
    • +a match is found as the value of the key-value pair corresponding to the +specified natural language of the languageMap (e.g. matches {"fr": "rouge", "en":"red","de": +"rot"} but not {"fr": "red", +"en":"black","de": "blue"}). +
      • +
    • +a match is found as a single element from the array of values of the +key-value pair corresponding to the specified natural language of the +languageMap (e.g. matches {"fr": ["chat", +"rouge"], "en":["red", "cat], "de": ["rote", "Katze"]} but not +{"fr": ["chat", "rouge"], "en" : ["coal", +"black"],"de": ["blaue", "Engel"]}). +
      • +
    • +
  • +The Query Term value target element corresponds to a +LanguageProperty and no natural language is specified e.g. color[*]=="red": +
    +
      +
    • +any match is found in the values of the key-value pairs of the +languageMap (e.g. matches {"fr": "rouge", +"en":"red", "de": "rote"}. +
      • +
    • +a match is found as a single element of the array of values of the +key-value pairs of the languageMap (e.g. matches {"fr": "chat", "rouge"], "en":["red", "cat"], "de": +["rote", "Katze"]}). +
      • +
    • +
  • +The Query Term value is a URI and the target element corresponds to a +Relationship, a ListRelationship or a +VocabProperty, e.g. color=="http://example/red" +
    • +
+
    +
  • +Is identical to the target value (e.g. matches "http://example.com/red"). +
    • +
  • +Is included in the target value, if the latter is an array (e.g. matches +["http://example.com/blue"," +http://example.com/red"," http://example.com/green"]). +
    • +
+
    +
  • +If the Query Term value target element corresponds to a +Relationship, a ListRelationship or a VocabProperty and is a list of +URIs (production rule named ValueList), e.g. color==" http://example/black","http://example/red": +
    • +
+
    +
  • +The target value is identical to any of the list values (e.g. matches +"http://example.com/red"). +
    • +
  • +The target value includes any of the Query Term values, if the target +value is an array (e.g. matches ["http://example.com/red", "http://example.com/blue"]). +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type, then it shall be considered as not matching. +
    • +
+
    +
  • +Unequal operator (production rule named unequal). A +matching entity shall contain the target element and meet any of the +following conditions: +
    • +
+
    +
  • +The Query Term value, e.g. color!="red": +
    • +
+
    +
  • +Is neither identical nor equivalent to the target value (e.g. matches +"black"). +
    • +
  • +Is not included in the target value, if the latter is an array (e.g. +matches ["blue","black","green"], +but not ["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a list of values (production rule named ValueList), e.g. +color!= "black", "red": +
    • +
+
    +
  • +The target value is neither identical nor equivalent to any of the list +values (e.g. matches "blue"). +
    • +
  • +The target value does not include any of the list values, if the target +value is an array (e.g. matches ["blue","yellow","green"], but not ["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a range (production rule named Range), e.g. temperature!=10..20: +
    • +
+
    +
  • +The target value is not in the interval between the minimum and the +maximum (both included) (e.g. matches 9). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and a natural language is specified e.g. color[en]!="red": +
    +
      +
    • +no matching value is found as the value of the specified language key of +a languageMap where a language filter is specified. (e.g. matches +{"fr": "noir", "en":"black","de": +"schwarz"} but not {"fr": "rouge", "en" : "red","de": "rot"}). +
      • +
    • +no matching value is found as a single element from the array of values +of the key-value pair corresponding to the specified natural language of +the languageMap (e.g. matches {"fr": +["chat", "rouge"], "en":["coal", "black"], "de": ["blaue", "Engel"]} +but not {"fr": ["rouge", "noir"], "en" : ["red", +"black"],"de": ["rot", "schwarz"]}). +
      • +
    • +
  • +The Query Term value target element corresponds to a +LanguageProperty and no language filter is specified e.g. color[*]!="red": +
    +
      +
    • +no matching value is found in any of the values of the key-value pairs +of a languageMap (e.g. matches {"fr": +"noir", "en":"black","de": "schwarz"}, but not {"fr": +"rouge", "en":"red","de": "rot"}). +
      • +
    • +no matching value is found as a single element from the array of values +of the key-value pair corresponding to the specified natural language of +the languageMap (e.g. matches {"fr": +["chat", "rouge"], "en":["coal", "black"], "de": ["blaue", "Engel"]} +but not {"fr": ["rouge", "noir"], +"en":["red", "black"],"de": ["rot", "schwartz"]}). +
      • +
    • +
  • +The Query Term value is a URI and the target element corresponds to a +Relationship, a ListRelationship or a +VocabProperty, e.g. color!="http://example.com/red": +
    • +
+
    +
  • +Is not identical to the target value (e.g. matches "http://example.com/black"). +
    • +
  • +Is not included in the target value, if the latter is an array (e.g. +matches ["http://example.com/blue", "http://example.com/black", "http://example.com/green"], but not ["http://example.com/blue", +"http://example.com/red", "http://example.com/green"]). +
    • +
+
    +
  • +If the Query Term value target element corresponds to a +Relationship, a ListRelationship or a VocabProperty and is a list of +URIs e.g. color!="http://example.com/black", " +http://example.com/red": +
    • +
+
    +
  • +The target value is not identical to any of the list values (e.g. +matches "http://example.com/blue"). +
    • +
  • +The target value does not include any of the list values, if the target +value is an array (e.g. matches ["http://example.com/blue", "http://example.com/yellow", "http://example.com/green"], but not ["http://example.com/blue", "http://example.com/red", "http://example.com/green"]). +
    • +
+
    +
  • +If the data type of the target value and the data type of the Query Term +value are different, then they shall be considered unequal. +
    • +
+
    +
  • +Greater than operator (production rule named greater). For an +entity to match, it shall contain the target element and the target +value has to be strictly greater than the Query Term value: +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type then it shall be considered as not matching. +
    • +
+
    +
  • +Less than operator (production rule named less). For an +entity to match, it shall contain the target element and the target +value shall be strictly less than the value: +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type then it shall be considered as not matching. +
    • +
+
    +
  • +Greater or equal than (production rule named greaterEq). A +matching entity shall meet any of the Greater than or the +Equal conditions for single values. +
    • +
  • +Less or equal than (production rule named lessEq). A matching +entity shall meet any of the Less than or the Equal +conditions for single values. +
    • +
  • +Match pattern (production rule named patternOp). A +matching entity shall contain the target element and the target value +shall be in the L(R) of the regular pattern specified by the Query Term: +
    • +
+
    +
  • +If the target value data type is different than String then it +shall be considered as not matching. +
    • +
+
    +
  • +Do not match pattern (production rule named +notPatternOp). A matching entity shall contain the target element +and the target value shall not be in the L(R) of the regular pattern +specified by the Query Term: +
    • +
+
    +
  • +If the target value data type is different than String then it +shall be considered as not matching. +
    • +
+

4.10 NGSI-LD +Geoquery Language

+

The NGSI-LD Geoquery language shall be supported by implementations. +It is intended to define predicates which allow testing whether a +specific topological spatial relationship exists between a pair of +geometries: a target geometry and a reference geometry. The target +geometry represents a geospatial Property of an Entity, typically, the +location of the Entity.

+

A total of four parameters are defined in order to fully specify an +NGSI-LD Geoquery:

+
    +
  • +georel, to express the desired geospatial relationship; +
    • +
  • +geometry, to express the type of the reference +geometry; +
    • +
  • +coordinates, to express the reference geometry; +
    • +
  • +geoproperty, to express the target geometry of an +Entity. This parameter is optional, location is the default. +
    • +
+

The following grammar defines the syntax for the geospatial +relationships (parameter name georel):

+
+andOp = %x3B ; ; +
+
+equal = %x3D %x3D ; == +
+
+georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel +/ equalsRel / disjointRel +
+
+nearRel = nearOp andOp distance equal PositiveNumber ; +near;max(min)Distance==x (in meters) +
+
+distance = "maxDistance" / "minDistance" +
+
+nearOp = "near" +
+
+withinRel = "within" +
+
+containsRel = "contains" +
+
+intersectsRel = "intersects" +
+
+equalsRel = "equals" +
+
+disjointRel = "disjoint" +
+
+overlapsRel = "overlaps" +
+
+ +
+

PositiveNumber +shall be a non-zero positive number as mandated by the JSON +Specification. Thus, it shall follow the ABNF Grammar, production rule +named Number, +section 6 of IETF RFC 8259 [6], excluding the 'minus' +symbol and excluding the number 0.

+

Reference geometries shall be specified by:

+
    +
  • +A geometry type (parameter name geometry) as defined by +the GeoJSON specification (IETF RFC 7946 [8], section 1.4), except +GeometryCollection. +
    • +
  • +A coordinates (parameter name coordinates) element +which shall represent the coordinates of the reference geometry as +mandated by IETF RFC 7946 [8], section 3.1.1. +
    • +
+

Target geometry, i.e. the target Entity's GeoProperty to which +the geoquery is to be applied, can be specified by an extra parameter +named geoproperty. The GeoProperty's name shall +be specified as short hand name and not a fully qualified one, because, +when the query language is used, an @context properly defining +all the terms (as per clause +5.5.7) shall be issued. If no geoproperty is specified, the +geoquery is applied to the default Property location (see +clause +4.7.1).

+

Note that proper URL encoding shall be used by HTTP binding API +clients when using these examples.

+
+EXAMPLE 1: ?georel=near;maxDistance==2000 +
+
+&geometry=Point +
+
+&coordinates=[8,40] +
+
+&geoproperty=observationSpace +
+
+ +
+
+EXAMPLE 2: ?georel=within +
+
+
+&geometry=Polygon +
+
+
+&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0], +
+
+[100.0,0.0]]] +
+
+&geoproperty=location +
+
+ +
+
+EXAMPLE 3: A query encoded as an HTTP Query String. Note that this is +HTTP binding specific, to be used via GET method, as defined in clause 6.4.3.2. +
+
+ ?georel=near;maxDistance==2000 +
+
+
+&geometry=Point +
+
+&coordinates=[8,40] +
+
+ +
+
+

The semantics of the different geospatial relationships defined above +is as follows, and shall be supported by compliant implementations:

+
    +
  • +near statement (production rule named nearRel): +
    • +
+
    +
  • +maxDistance +modifier. For an entity to match it has to be within the buffer +geometric object (as defined by [14]) given by the reference +geometry, with distance (in meters) equal to the number conveyed +(production rule named PositiveNumber). +
    • +
  • +minDistance +modifier. For an entity to match it has to be disjoint with the buffer +geometric object (as defined by [14]) given by the reference +geometry, with distance (in meters) equal to the number conveyed +(production rule named PositiveNumber). +
    • +
+
    +
  • +equals relationship (production rule named equalsRel). For an +entity to match, the target geometry shall be equal, as specified by +[14], to the +reference geometry. +
    • +
  • +disjoint relationship (production rule named disjointRel). For +an entity to match, the target geometry shall be disjoint, as specified +by [14], to the +reference geometry. +
    • +
  • +intersects relationship (production rule named intersectsRel). For +an entity to match, the target geometry shall intersect, as specified by +[14], with the +reference geometry. +
    • +
  • +within relationship (production rule named +withinRel). For an entity to match, the target geometry shall be +within, as specified by [14], the reference geometry. +
    • +
  • +contains relationship (production rule named containsRel). For +an entity to match, the target geometry shall contain, as specified by +[14], the reference +geometry. +
    • +
  • +overlaps relationship (production rule named overlapsRel). For +an entity to match, the target geometry shall overlap, as specified by +[14], the reference +geometry. +
    • +
+

When resolving geo-queries, Entities which do not convey the target +GeoProperty of the query shall be considered as non-matching.

+

4.11 NGSI-LD Temporal Query +Language

+

The NGSI-LD Temporal Query language shall be supported by +implementations. It is intended to define predicates which allow testing +whether Temporal Properties of NGSI-LD Entities, Properties and +Relationships, are within certain temporal constraints. In particular it +can be used to request historic Property values and Relationships that +were valid within the specified timeframe.

+

The following grammar defines the syntax that shall be supported:

+
+timerel = beforeRel / afterRel / betweenRel +
+
+beforeRel = "before" +
+
+afterRel = "after" +
+
+betweenRel = "between" +
+
+ +
+

The points in time for comparison are defined as follows:

+
    +
  • +A timeAt parameter, which shall represent the +comparison point for the before and after relation and the +starting point for the between relation. It shall be represented +as DateTime (mandated by clause +4.6.3). +
    • +
  • +An endTimeAt parameter, which is only used for the +between relation and shall represent the end point for +comparison. It shall be represented as DateTime (mandated by clause +4.6.3). +
    • +
+

The Temporal Property (see clause +4.8) to which the temporal query is to be applied can be specified +by timeproperty. If no timeproperty is +specified, the temporal query is applied to the default Temporal +Property observedAt.

+
+EXAMPLE 1: ?timerel=before +
+
+&timeAt=2017-12-13T14:20:00Z +
+
+ +
+
+EXAMPLE 2: ?timerel=between +
+
+&timeAt=2017-12-13T14:20:00Z +
+
+&endTimeAt=2017-12-13T14:40:00Z +
+
+&timeproperty=modifiedAt +
+
+ +
+
+EXAMPLE 3: Temporal query encoded as HTTP Query String, note that this is +HTTP binding specific, to be used via GET method, as defined in clause 6.18.3.2. +
+
+ ?timerel=between +
+
+
+&timeproperty=observedAt +
+
+&timeAt=2017-12-13T14:20:00Z +
+
+ +
+
+

The semantics of the different temporal relations defined above is as +follows, and shall be supported by compliant implementations:

+
    +
  • +before relationship (production rule named beforeRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be before the time specified by +timeAt; +
    • +
  • +after relationship (production rule named afterRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be after the time specified by +timeAt; +
    • +
  • +between relationship (production rule named betweenRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be after the time specified by +timeAt and before the time specified by endTimeAt. +
    • +
+

When resolving temporal queries, Entities which do not convey the +target Temporal Property of the query shall be considered as +non-matching.

+

4.12 NGSI-LD +Pagination

+

NGSI-LD operations can potentially return a result set including a +large number of NGSI-LD Elements, so that pagination of query results +shall be supported by compliant implementations.

+

The list of operations that incur this behaviour is as follows:

+ +

Nonetheless, the NGSI-LD API is agnostic about specific pagination +mechanisms and only defines the behaviour that shall be observed by +NGSI-LD Systems.

+

For each operation above, NGSI-LD Systems shall:

+
    +
  • +provide a mechanism to iterate through the NGSI-LD Elements of a result +set without exhausting NGSI-LD Client or Broker resources; +
    • +
  • +provide a mechanism to flag NGSI-LD Clients when there are remaining +NGSI-LD Elements to be traversed as part of a result set; +
    • +
  • +allow NGSI-LD Clients specifying a limit (page size), as a parameter of +API operations, to the number of NGSI-LD Elements (at a maximum) +retrieved by the implementation for each pagination iteration; +
    • +
  • +define a default limit (default page size) to the +number of NGSI-LD Elements retrieved per pagination iteration; +
    • +
  • +allow NGSI-LD Clients iterating forwards and backwards through a result +set. +
    • +
+

NGSI-LD implementations should:

+
    +
  • +avoid Denial of Service attacks or other potential security risks, by +defining a hard limit to the size of generated response payload body +while paginating. For instance, certain queries can be rejected by +issuing an error of type TooManyResults. +
    • +
+

NGSI-LD implementations may:

+
    +
  • +warn NGSI-LD Clients when result sets become invalid due to dynamic +changes in NGSI-LD Elements (additions, deletions) occurred while +iterating over pages. +
    • +
+

The concrete realization of the features described above might depend +on each API binding. Nonetheless, NGSI-LD Systems shall implement +pagination features as mandated by the present clause, for any API +binding.

+

4.13 Counting the Number of +Results

+

Given that NGSI-LD Query operations can potentially return a result +set including a large number of NGSI-LD Elements and that pagination of +query results shall be supported (see clause +4.12), compliant implementations shall also support a mechanism for +relaying to the client the number of expected resulting elements, when a +query is executed.

+

A specific field (e.g. a custom header in the response in case of +HTTP binding, see clause +6.3.13) shall be returned within the response of a query, whenever +this is requested by the client.

+

Mechanisms for limiting the number of returned NGSI-LD Elements are +independent of the counting mechanism, so that, potentially, a client +can issue a query that limits to zero the number of desired results but +asks for the count to be present.

+

This is useful for client-side planning and fine-tuning of subsequent +queries and their parameters.

+

4.14 Supporting Multiple Tenants

+

The concept of a Tenant is that a +user or group of users utilizes a single instance of an NGSI-LD system +(Context Source or Context Broker) in isolation from other +users or groups of users of the same instance, which are considered to +be different Tenants. Thus a multi-tenant NGSI-LD system is a +system where a single software instance is used by different users or +groups of users, the Tenants, where 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. Typically, multi-tenancy is +used together with an access control mechanism, enforcing the isolation +of Tenants, however access control and other +security-related aspects are out-of-scope of the present document.

+

The NGSI-LD API optionally enables multi-tenant systems. To support +this, Tenant information can be +optionally specified in NGSI-LD API operations. The operation then only +applies to the targeted Tenant. As +all information of one Tenant is +isolated from other Tenants, the NGSI-LD API operations for managing, +retrieving and subscribing to entity information, but also any context +source related operations only apply to the information of the specified +Tenant in isolation and never have +any effect on the information of other Tenants.

+

As the support and use of Tenants +is optional, any operation not explicitly specifying a Tenant targets a default Tenant, which always exists. NGSI-LD +systems not supporting multiple Tenants +should raise an error of type NoMultiTenantSupport if a Tenant is specified. To enable Context Sources to be part of tenant-based +distributed or federated systems, Tenant information can optionally be +specified in Context Source +Registrations. When contacting the respective Context Sources, the Tenant information from the Context Source Registration has to be used. +If no Tenant information is present +in the Context Source Registration, +no Tenant information is to be used +and thus the default Tenant is +targeted on the registered Context +Source. This enables integrating Context Sources not supporting +multi-tenancy in a distributed system with a Tenant-based Context Broker or integrating local Tenants +in a federated system using a different Tenant.

+

4.15 NGSI-LD +Language Filter

+

The NGSI-LD Language Filter shall be supported by implementations. It +is intended to form a mechanism which allows just one matching string +value of LanguageProperties of NGSI-LD Entities to be converted +to an NGSI-LD Property, where the value will be a string for the +specified natural language.

+

The following grammar defines the syntax that shall be supported by +the filter:

+
+lang = langtag +
+
+ +
+

Where the langtag is defined according to the rules as mandated by +IETF RFC 5646 [28], +and IETF RFC 3282 [29]. If the Context Broker cannot serve any matching +language, it shall default to any supported language. This behavior can +be triggered by specifying lang="*" in the filter (see +example 3).

+

In any case, the attribute in question shall be augmented with an +additional non-reified subproperty lang indicating the actual +language returned.

+
+EXAMPLE 1: Specified natural language - return LanguageProperties as +strings in English only. +
+
+ lang="en" +
+
+EXAMPLE 2: Multiple natural languages with no ranked preference - return +LanguageProperties as strings in either Swiss French or French. +
+
+ lang="fr-CH,fr" +
+
+EXAMPLE 3: Wildcard - return LanguageProperties as a string in any +supported language. +
+
+ lang="*" +
+
+EXAMPLE 4: Quality value ranking - return all LanguageProperties as a +string in Swiss French or French with no ranked preference, fallback to +English as a second choice and finally fallback to any other supported +language. +
+
+ lang="fr-CH,fr;q=0.9,en;q=0.8,*;q=0.5" +
+

4.16 Supporting Multiple Entity +Types

+

From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any +Entity are supported. An Entity is uniquely identified by its id, so +whenever information is provided for an Entity with a given id, it is +considered part of the same Entity, regardless of the Entity Type(s) +specified. To avoid unexpected behaviour, Entity Types can be implicitly +added by all operations that update or append attributes. There is no +operation to remove Entity Types from an Entity. The philosophy here is +to assume that an Entity always had all Entity Types, but possibly not +all Entity Types have previously been known in the system. The only +option to remove an Entity Type is to delete the Entity and re-create it +with the same id. Alternatively, a batch upsert with 'replace' update +mode can be used, as described in clause +5.6.8.

+

4.17 NGSI-LD Entity Type +Selection Language

+

The NGSI-LD Entity Type Selection Language shall be supported by +implementations. It is intended to select only those Entities that have +the specified Entity Type(s), possibly among others. Entity Types are +specified as a disjunction of elements, where each element can either +directly be an Entity Type or a conjunction of multiple Entity Types. +The logical operators are the same as in the NGSI-LD Query Language +specified in clause +4.9. As a disjunction of Entity Types can also be seen as a list, +and to be compatible with previous versions of the NGSI-LD API, a comma +can be used as an alternative representation of the or operator. +For logical and grouping parenthesis are needed.

+
+ +
+
+EntityTypes = OrEntityType *(orOp OrEntityType) ; OrEntityType|OrEntityType +
+
+OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType) +
+
+OrEntityType = EntityType                        ; EntityType +
+
+andOp = %x3B                        ; ; +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ +
+

EntityType is +either a valid name as specified in clause +4.6.2 or a URI.

+
+EXAMPLE 1: Entities of type Building or House: +
+
+Building|House +
+
+Alternative Representation: +
+
+Building,House +
+
+EXAMPLE 2: Entities of type Home and Vehicle: +
+
+(Home;Vehicle) +
+
+EXAMPLE 3: Entities of type (Home and Vehicle) or Motorhome: +
+
+(Home;Vehicle)|Motorhome +
+
+Alternative Representation: +
+
+(Home;Vehicle),Motorhome +
+
+NOTE: The special characters ",", ";", "(" and +")" used in the Entity Type +Selection Language are allowed characters in URIs. The use of short +names is recommended. +
+

4.18 NGSI-LD Scopes

+

An NGSI-LD Scope enables putting Entities into a hierarchical +structure and restrict results of queries and notifications accordingly. +The hierarchical structure is user-defined, e.g. according to (logical) +location or organization. The use of Scopes is optional and an Entity +can be assigned to one or more Scopes at the same time. The Scope is +represented as a special scope Property that is non-reified in +the normalized Entity representation and reified in the temporal +representation of an Entity. In the latter case, it is restricted to +having the non-reified Temporal Properties createdAt, modifiedAt +and deletedAt as sub-Properties. There shall at most be one +instance of the scope property per Entity. In case multiple +representations of the same Entity have to be merged, e.g. when +combining the results of distributed queries, the values of scope +are merged. The value of scope is represented as a JSON +array in case there is more than one Scope. For the Temporal Evolution a +given Scope is considered valid from the time it has been set until the +time it has been explicitly removed by an update or delete operation +(for an example see annex +C, clause +C.5.16).

+

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

+
+Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)                        ; [/] ScopeLevel *(/ScopeLevel) +
+
+ScopeLevel = unicodeLetter *ScopeLevelChar +
+
+ScopeLevelChar = unicodeNumber / unicodeLetter +
+
+ScopeLevelChar =/ %x5F                                              ; _ +
+
+ +
+
+EXAMPLE 1: /Madrid +
+
+EXAMPLE 2: +Madrid +
+
+EXAMPLE 3: /Madrid/Gardens/ParqueNorte +
+
+EXAMPLE 4: /CompanyA/OrganizationB/UnitC +
+

4.19 NGSI-LD +Scope Query Language

+

The NGSI-LD Scope Query Language shall be supported by +implementations. It is intended to select only those Entities that are +within the specified Scope(s). Scopes are specified as a disjunction of +elements, where each element can either directly be a Scope or a +conjunction of multiple Scopes. The "+" +can be used as a wildcard to match a single scope level within a Scope. +The "#" that can be added at the end of a +Scope specification serves as a wildcard, which matches the given scope +and the whole hierarchy of scopes below. The "/#" matches any non-empty scope, i.e. only +explicitly specified scopes. The logical operators are the same as in +the NGSI-LD Query Language specified in clause +4.9. As a disjunction of Scopes can also be seen as a list, a comma +can be used as an alternative representation of the or operator. +For logical and grouping parenthesis are needed.

+
+ +
+
+ScopesQ = OrScopeQ *(orOp OrScopeQ) ; OrScopeQ|OrScopeQ +
+
+ScopesQ =/ %x2F %23 ; / # +
+
+OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29             ; (ScopeQ;ScopeQ) +
+
+OrScopeQ =/ ScopeQ *1(%x2F %23)                          ; ScopeQ / # +
+
+andOp = %x3B                        ; ; +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel) +
+
+ScopeQLevel = unicodeLetter *ScopeQLevelChar +
+
+ScopeQLevel =/ %x2B ; +  +
+
+ScopeQLevelChar = unicodeNumber / unicodeLetter +
+
+ScopeQLevelChar =/ %x5F                                             ; _ +
+
+ +
+
+EXAMPLE 1: Scope /Madrid: +
+
+/Madrid +
+
+EXAMPLE 2: Scope /Madrid/Gardens and the whole scope tree below: +
+
+/Madrid/Gardens/#, e.g. matches the +following Scopes: +
+
+/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur +
+
+EXAMPLE 3: Scopes /Madrid/Gardens/ParqueNorte and +/Madrid/Sights/ParqueNorte, or any other Scope with Madrid as first +scope level and ParqueNorte as third scope level: +
+
+
+/Madrid/+/ParqueNorte +
+
+
+EXAMPLE 4: Scope /Madrid/Districts and /CompanyA: +
+
+(/Madrid/Districts;/CompanyA) +
+
+EXAMPLE 5: Scope (/Madrid/Districts and /CompanyA) or /CompanyB: +
+
+(/Madrid/Districts;/CompanyA)|CompanyB +
+
+Alternative Representation: +
+
+(/Madrid/Districts;/CompanyA),CompanyB +
+

4.20 NGSI-LD Distributed +Operation names

+

When registering Context Sources +(see clause +5.2.9), the registrant NGSI-LD interface endpoint may optionally +offer a subset of NGSI-LD operations which it accepts. Table +4.20‑1 defines a list of names for each of these operations.

+
+Table 4.20-1: Names of implemented Operations +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+Operation name +
+Implements +
+Context Information Provision +
+createEntity +
+5.6.1 Create Entity +
+updateEntity +
+5.6.2 Update Attributes +
+appendAttrs +
+5.6.3 Append Attributes +
+updateAttrs +
+5.6.4 Partial Attribute update +
+deleteAttrs +
+5.6.5 Delete Attribute +
+deleteEntity +
+5.6.6 Delete Entity +
+createBatch +
+5.6.7 Batch Entity Creation +
+upsertBatch +
+5.6.8 Batch Entity Creation or Update (Upsert) +
+updateBatch +
+5.6.9 Batch Entity Update +
+deleteBatch +
+5.6.10 Batch Entity Delete +
+upsertTemporal +
+5.6.11 Create or Update Temporal Evolution of an Entity +
+appendAttrsTemporal +
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+deleteAttrsTemporal +
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+updateAttrInstanceTemporal +
+5.6.14 Partial Update Attribute Instance in Temporal Evolution of an +Entity +
+deleteAttrInstanceTemporal +
+5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity +
+deleteTemporal +
+5.6.16 Delete Temporal Evolution of an Entity +
+mergeEntity +
+5.6.17 Merge Entity +
+replaceEntity +
+5.6.18 Replace Entity +
+replaceAttrs +
+5.6.19 Replace Attribute +
+mergeBatch +
+5.6.20 Batch Entity Merge +
+Context Information Consumption +
+retrieveEntity +
+5.7.1 Retrieve Entity +
+queryEntity +
+5.7.2 Query Entities (excluding batch entity queries) +
+queryBatch +
+5.7.2 Query Entities (batch entity queries only) +
+retrieveTemporal +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+queryTemporal +
+5.7.4 Query Temporal Evolution of Entities +
+retrieveEntityTypes +
+5.7.5 Retrieve Available Entity Types +
+retrieveEntityTypeDetails +
+5.7.6 Retrieve Details of Available Entity Types +
+retrieveEntityTypeInfo +
+5.7.7 Retrieve Available Entity Type Information +
+retrieveAttrTypes +
+5.7.8 Retrieve Available Attributes +
+retrieveAttrTypeDetails +
+5.7.9 Retrieve Details of Available Attributes +
+retrieveAttrTypeInfo +
+5.7.10 Retrieve Available Attribute Information +
+Context Information Subscription +
+createSubscription +
+5.8.1 Create Subscription +
+updateSubscription +
+5.8.2 Update Subscription +
+retrieveSubscription +
+5.8.3 Retrieve Subscription +
+querySubscription +
+5.8.4 Query Subscription +
+deleteSubscription +
+5.8.5 Delete Subscription +
+

In addition to these individual operations, a series of names for +common groups of operations have also been defined. Table +4.20‑2 defines a list of names for each of these operation +groups.

+
+Table 4.20-2: Named Operation Groups +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+Operation Group name +
+Implements +
+federationOps +
    +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
  • +queryBatch +
    • +
  • +retrieveEntityTypes +
    • +
  • +retrieveEntityTypeDetails +
    • +
  • +retrieveEntityTypeInfo +
    • +
  • +retrieveAttrTypes +
    • +
  • +retrieveAttrTypeDetails +
    • +
  • +retrieveAttrTypeInfo +
    • +
  • +createSubscription +
    • +
  • +updateSubscription +
    • +
  • +retrieveSubscription +
    • +
  • +querySubscription +
    • +
  • +deleteSubscription +
    • +
+updateOps +
    +
  • +updateEntity +
    • +
  • +updateAttrs +
    • +
  • +replaceEntity +
    • +
  • +replaceAttrs +
    • +
+retrieveOps +
    +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
+redirectionOps +
    +
  • +createEntity +
    • +
  • +updateEntity +
    • +
  • +appendAttrs +
    • +
  • +updateAttrs +
    • +
  • +deleteAttrs +
    • +
  • +deleteEntity +
    • +
  • +mergeEntity +
    • +
  • +replaceEntity +
    • +
  • +replaceAttrs +
    • +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
  • +retrieveEntityTypes +
    • +
  • +retrieveEntityTypeDetails +
    • +
  • +retrieveEntityTypeInfo +
    • +
  • +retrieveAttrTypes +
    • +
  • +retrieveAttrTypeDetails +
    • +
  • +retrieveAttrTypeInfo +
    • +
+

If no specific subset of operations is defined for a Context Source Registration, the default +set of operations matches the group defined as "federationOps".

+

4.21 NGSI-LD Attribute +Projection Language

+

The NGSI-LD Attribute Projection Language shall be supported by +implementations for projection parameters (e.g. pick and +omit). Its aim is to specify the Attributes to be retrieved +within an Entity (or associated Linked +Entities when Linked Entity Retrieval is used). Projected +Attributes are specified as a disjunction of elements, where each +element can either directly be an Attribute name, or in the case of +Linked Entity Retrieval, a Relationship name followed by an Attribute +name within the Linked Entity. Since +a disjunction of Attributes is a list, either a comma or a pipe +character can be used as alternative representations of the or +operator. In the following, ABNF grammar for NGSI-LD Attribute +Projection Language is given.

+
+ +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm) +
+
+LinkedEntityTerm  = %x7B ProjectionTerm %x7D ; {ProjectionTerm} +
+
+ +
+

See clause +4.9 for the definition of AttrName.

+
+EXAMPLE 1: ?pick=temperature +
+
+EXAMPLE 2: ?pick=temperature,humidity +
+
+EXAMPLE 3: ?pick=observation{temperature,humidity} +
+
+ +
+
+ + diff --git a/public/11-tabapi-http-binding.html b/public/11-tabapi-http-binding.html new file mode 100644 index 0000000000000000000000000000000000000000..3fa8e118960cff0dd90638d143d88cc0775f094f --- /dev/null +++ b/public/11-tabapi-http-binding.html @@ -0,0 +1,18850 @@ + + + + + + + 6 API HTTP Binding + + + + + + + + +

6 API +HTTP Binding

+

6.1 Introduction

+

This clause defines the resources and operations of the NGSI-LD API. +The NGSI-LD API is structured in terms of HTTP [3], [4] verbs, request and response +payload bodies.

+

A non-normative OAS specification [i.12] of the referred HTTP +binding can be found at [i.14].

+

6.2 Global Definitions +and Resource Structure

+

All resource URIs of this API shall have the following root:

+
    +
  • +{apiRoot}/{apiName}/{apiVersion}/ +
    • +
+
+
+NOTE 1: +
+
+The + +apiRoot + +discovery + +process + +is + +out + +of + +the + +scope + +of + +the + +present + +document. +
+
+
+
+NOTE 2: +
+
+The + +apiRoot + +for + +Context Source + +related + +aspects + +and + +the + +apiRoot + +for + +general + +Entity-related + +aspects + +can + +be + +different, + +e.g. + +the + +Context Source + +related + +aspects + +can + +be + +implemented + +by + +a + +Context Registry + +as + +shown + +for + +the + +distributed + +and + +federated + +architectures + +(see + +clause +4.3 +), + +whereas + +the + +Entity-related + +aspects + +would + +be + +implemented + +by + +a + +Context Broker +. +
+
+
+
+NOTE 3: +
+
+The + +apiRoot + +for + +Context Source + +related + +aspects + +and + +the + +apiRoot + +for + +general + +Entity-related + +aspects + +can + +be + +different + +than + +the + +apiRoot + +for + +temporal + +aspects, + +e.g. + +the + +temporal + +aspects + +can + +be + +implemented + +by + +an + +NGSI-LD + +subsystem + +specialized + +in + +historical + +data. +
+
+

The apiRoot includes the scheme ("http" or "https"), host and +optional port, and an optional prefix string. The API shall support HTTP +over TLS (also known as HTTPS - see IETF RFC 2818 [18]). TLS version 1.2 as +defined by IETF RFC 5246 [19] shall be supported. HTTP +without TLS is not recommended.

+

The apiName shall be set to "ngsi-ld" and the apiVersion shall be +set to "v1" for the present document.

+

All resource URIs are defined relative to the above root URI. The +structure of the resources under the root URI is shown in Figure 6.2‑1 and +methods defined on them are shown in Table 6.2‑1.

+
+ +
+
+Figure 6.2-1: Resource URI structure of the NGSI-LD API +
+
+Table 6.2-1: Resources and HTTP methods defined on them +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Resource Name +
+Resource URI +
+HTTP Method +
+Meaning +
+Clauses +
+Entity List +
+/entities/ +
+POST +
+Entity creation +
+5.6.1; 6.4.3.1 +
+GET +
+Query entities +
+5.7.2; 6.4.3.2 +
+DELETE +
+Purge entities +
+5.6.21; 6.4.3.3 +
+Entity by id +
+/entities/{entityId} +
+GET +
+Entity retrieval by id +
+5.7.1; 6.5.3.1 +
+DELETE +
+Entity deletion by id +
+5.6.6; 6.5.3.2 +
+PATCH +
+Entity merge by id +
+5.6.17; 6.5.3.4 +
+PUT +
+Entity replacement by id +
+5.6.18; 6.5.3.3 +
+Attribute List +
+/entities/{entityId}/attrs/ +
+POST +
+Append Attributes to Entity +
+5.6.3; 6.6.3.1 +
+PATCH +
+Update Attributes of an Entity +
+5.6.2; 6.6.3.2 +
+Attribute by id +
+/entities/{entityId}/attrs/{attrId} +
+PATCH +
+Partial Attribute update +
+5.6.4; 6.7.3.1 +
+DELETE +
+Attribute deletion +
+5.6.5; 6.7.3.2 +
+PUT +
+Attribute replacement +
+5.6.19; 6.7.3.3 +
+Subscriptions List +
+/subscriptions/ +
+POST +
+Create Subscription +
+5.8.1; 6.10.3.1 +
+GET +
+Retrieve list of Subscriptions +
+5.8.4; 6.10.3.2 +
+Subscription by Id +
+/subscriptions/{subscriptionId} +
+GET +
+Subscription retrieval by id +
+5.8.3; 6.11.3.1 +
+PATCH +
+Subscription update by id +
+5.8.2; 6.11.3.2 +
+DELETE +
+Subscription deletion by id +
+5.8.5; 6.11.3.3 +
+Entity Types +
+/types/ +
+GET +
+Retrieve available entity types +
+5.7.5 and 5.7.6; 6.25.3.1 +
+Entity Type +
+/types/{type} +
+GET +
+Details about available entity type +
+5.7.7; 6.26.3.1 +
+Attributes +
+/attributes/ +
+GET +
+Available attributes +
+5.7.8 and 5.7.9; 6.27.3.1 +
+Attribute +
+/attributes/{attrId} +
+GET +
+Details about available attribute +
+5.7.10; 6.28.3.1 +
+Context source registration list +
+/csourceRegistrations/ +
+POST +
+Csource registration creation +
+5.9.2; 6.8.3.1 +
+GET +
+Discover Csource registrations +
+5.10.2; 6.8.3.2 +
+Context source registration by Id +
+/csourceRegistrations/{registrationId} +
+GET +
+Csource registration retrieval by id +
+5.10.1; 6.9.3.1 +
+PATCH +
+Csource registration update by id +
+5.9.3; 6.9.3.2 +
+DELETE +
+Csource registration deletion by id +
+5.9.4; 6.9.3.3 +
+Context source registration subscription list +
+/csourceSubscriptions/ +
+POST +
+Create subscription to Csource registration +
+5.11.2; 6.12.3.1 +
+GET +
+Retrieval of list of subscription to Csource registration +
+5.11.5; 6.12.3.2 +
+Context source registration subscription by Id +
+/csourceSubscriptions/{subscriptionId} +
+GET +
+Csource registration subscription retrieval by id +
+5.11.4; 6.13.3.1 +
+PATCH +
+Csource registration subscription update by id +
+5.11.3; 6.13.3.2 +
+DELETE +
+Csource registration subscription deletion by id +
+5.11.6; 6.13.3.3 +
+Entity Operations. Create +
+/entityOperations/create +
+POST +
+Batch Entity creation +
+5.6.7; 6.14.3.1 +
+Entity Operations. Upsert +
+/entityOperations/upsert +
+POST +
+Batch Entity creation or update (upsert) +
+5.6.8; 6.15.3.1 +
+Entity Operations. Update +
+/entityOperations/update +
+POST +
+Batch Entity update +
+5.6.9; 6.16.3.1 +
+Entity Operations. Delete +
+/entityOperations/delete +
+POST +
+Batch Entity deletion +
+5.6.10; 6.17.3.1 +
+Entity Operations. Query +
+/entityOperations/query +
+POST +
+Query entities based on POST +
+5.7.2; 6.23.3.1 +
+Entity Operations. +
+
+Merge +
+/entityOperations/merge +
+POST +
+Batch Entity merge +
+5.6.20; 6.31.3.1 +
+Temporal Evolution of Entities +
+/temporal/entities/ +
+POST +
+Temporal Evolution of an Entity creation +
+5.6.11; 6.18.3.1 +
+GET +
+Query Temporal Evolution of Entities +
+5.7.4; 6.18.3.2 +
+Temporal Evolution of an Entity by id +
+/temporal/entities/{entityId} +
+GET +
+Temporal Evolution of an Entity retrieval by id +
+5.7.3; 6.19.3.1 +
+DELETE +
+Temporal Evolution of an Entity deletion by id +
+5.6.16; 6.18.3.2 +
+Temporal Representation of Attribute List +
+/temporal/entities/{entityId}/attrs/ +
+POST +
+Temporal Evolution of Attribute of an Entity instance addition +
+5.6.12; 6.20.3.1 +
+Temporal Representation of Attribute by id +
+/temporal/entities/{entityId}/attrs/{attrId} +
+DELETE +
+Attribute from Temporal Evolution of an Entity deletion +
+5.6.13; 6.21.3.1 +
+Temporal Representation of Attribute Instance by id +
+/temporal/entities/{entityId}/attrs/{attrId} /{instanceId} +
+PATCH +
+Attribute Instance from Temporal Evolution of an Entity update by +instance id +
+5.6.14; 6.22.3.1 +
+DELETE +
+Attribute Instance from Temporal Evolution of an Entity deletion by +instance id +
+5.6.15; 6.22.3.2 +
+Create EntityMap for Query Temporal Evolution of Entities +
+/temporal/entityMaps/ +
+GET +
+Query temporal evolution of entities for creating entity map +
+5.15.4; +
+
+6.35.3.1 +
+POST +
+Query temporal evolution of entities for creating entity map based on +POST +
+5.15.4; +
+
+6.35.3.2 +
+Temporal Query Operation +
+/temporal/entityOperations/query +
+POST +
+Query Temporal Evolution of Entities based on POST +
+5.7.4; 6.24.3.1 +
+Add and List @context +
+/jsonldContexts +
+POST +
+Add a user @context to the internal cache +
+5.13.2; 6.29.3.1 +
+GET +
+List all cached @contexts +
+5.13.3; 6.29.3.2 +
+Serve, Delete and Reload @context +
+/jsonldContexts/{contextId} +
+GET +
+Serve one specific user @context +
+5.13.4; 6.30.3.1 +
+DELETE +
+Delete one specific @context from internal cache, possibly re-inserting +a freshly downloaded copy of it +
+5.13.5; 6.30.3.2 +
+Create EntityMap for Query Entities +
+/entityMaps/ +
+GET +
+Query entities for creating entity map +
+5.14.4; +
+
+6.34.3.1 +
+POST +
+Query entities for creating entity map based on POST +
+5.14.4; +
+
+6.34.3.2 +
+Retrieve, Update and Delete Entity Maps +
+/entityMaps/{entityMapId} +
+GET +
+EntityMap Retrieval by id +
+5.14.1; 6.32.3.1 +
+PATCH +
+EntityMap Update by id +
+5.14.2; 6.32.3.2 +
+DELETE +
+EntityMap Deletion by id +
+5.14.3; 6.32.3.3 +
+Retrieve Context Source Identity Information +
+/info/sourceIdentity +
+GET +
+Context Source Identity Retrieval +
+5.15.1; 6.33.3.1 +
+

6.3 Common +Behaviours

+

6.3.1 Introduction

+

This clause extends the API common behaviours to the particularities +of the HTTP REST binding. For each operation implementations shall +exhibit the common behaviours as specified by clause +5.5 and the behaviours defined by the present clause.

+

6.3.2 Error Types

+

This clause associates API error types (which shall be contained in +the response payload body) defined by clause +5.5.2 with HTTP status codes as shown in Table 6.3.2‑1.

+
+Table 6.3.2-1: Mapping of error types to HTTP status codes +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Error Type +
+HTTP status +
+https://uri.etsi.org/ngsi-ld/errors/InvalidRequest +
+400 +
+https://uri.etsi.org/ngsi-ld/errors/BadRequestData +
+400 +
+https://uri.etsi.org/ngsi-ld/errors/AlreadyExists +
+409 +
+https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported +
+422 +
+https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound +
+404 +
+https://uri.etsi.org/ngsi-ld/errors/InternalError +
+500 +
+https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery +
+403 +
+https://uri.etsi.org/ngsi-ld/errors/TooManyResults +
+403 +
+https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable +
+504 +
+https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport +
+501 +
+https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant +
+404 +
+

In addition, implementations shall support the standard specific +errors of HTTP bindings, such as the following:

+
    +
  • +"Method Not Allowed" (405) which shall be raised when a client invokes a +wrong HTTP verb over a resource. Implementations shall provide the +allowed HTTP methods as mandated by IETF RFC 7231 [3] in section 6.5.5. +
    • +
  • +"Request Entity too large" (413) which shall be raised when the HTTP +input data stream provided by a client was too large i.e. too many +bytes. +
    • +
  • +"Length required" (411) which shall be raised when an HTTP request +provided by a client does not define the "Content-Length" HTTP header. +
    • +
  • +"Unsupported Media Type" (415) which shall be raised when an HTTP +request payload body (as per the "Content-Type" header) it is not "application/json" nor "application/ld+json". +
    • +
  • +"Not Acceptable" 406) which shall be raised +when the response media types that are acceptable by a client (as per +the "Accept" header) do not include or expand to "application/json" nor "application/ld+json". +
    • +
+

6.3.3 Reporting +errors

+

When an API operation results in an error, implementations shall +return an HTTP response as follows:

+
    +
  • +Content-Type: application/json. +
    • +
  • +HTTP Status Code: As per clause 6.3.2 +depending on error type. +
    • +
  • +Payload body: A JSON object including all the terms defined by clause +5.5.3. +
    • +
+

6.3.4 HTTP +request preconditions

+

For HTTP POST, PATCH and PUT HTTP requests implementations shall +check the following preconditions:

+
    +
  • +Content-Type header shall be "application/json" or "application/ld+json". +
    • +
  • +Content-Length header shall include the length of the request payload +body. +
    • +
+

For HTTP PATCH requests "application/merge-patch+json" is allowed as +Content-Type, as mandated by IETF RFC 7396 [16]. Implementations shall +interpret such MIME type as equivalent to "application/json".

+

For HTTP GET requests and for HTTP POST operations corresponding to +“Query Entities” (see clause +5.7.2) and “Query Temporal Evolutions of Entities” (see clause +5.7.4), implementations shall check the following preconditions:

+
    +
  • +Accept header shall include (or define a media range that can be +expanded to) at least one of: +
    • +
+
    +
  • +"application/json" +
    • +
  • +"application/ld+json" +
    • +
  • +"application/geo+json" +
    • +
+

The order of the list above is significant. If the Accept header can +be expanded to more than one of the options of the list, the first one +of the list shall be selected, unless amended by the HTTP Accept header +processing rules, e.g. the presence of a "q" parameter indicating a relative weight, (as +mandated by IETF RFC 7231 [3], section 5.3.2) require +otherwise.

+

If the Accept header is not present, "application/json" shall be assumed.

+

If an incoming HTTP request does not meet the preconditions stated +above, an HTTP error response of type InvalidRequest shall be +returned, with the following exceptions:

+
    +
  • +"Content-Length" HTTP header absence, shall result in just a +411 HTTP status code (without any payload body). +
    • +
  • +Unsupported Media Type, i.e. "Content-Type" header is not "application/json" nor "application/ld+json", shall result in just a +415 HTTP status code (without any payload body). +
    • +
  • +Not Acceptable Media Type, i.e. "Accept" header does not imply "application/json" nor "application/ld+json", shall result in a +406 HTTP status code and the body of the message shall +contain the list of the available representations of the resources. +
    • +
+

Notwithstanding the above, if the Accept Header is set to "application/geo+json":

+
    +
  • +For Context Information Consumption operations only, specifically +"Retrieve Entity" (see clause +5.7.1) and "Query Entity" (clause +5.7.2) GeoJSON is considered as an acceptable content type and a +GeoJSON payload will be returned. +
    • +
  • +For all other operations, the request will result in a Not Acceptable +Media Type error, returning a 406 HTTP status code and +the body of the message shall contain the list of the available +representations of the resources. +
    • +
+

6.3.5 JSON-LD +@context resolution

+

In the HTTP REST binding, implementations shall resolve the JSON-LD +@context associated to an incoming HTTP request as follows:

+
    +
  • +If the request verb is GET or DELETE, then the associated JSON-LD +@context shall be obtained from a Link header [7] as mandated by JSON-LD +[2], section 6.2. In +the absence of such Link header, then the associated @context +shall be the default JSON-LD @context. +
    • +
+
+
+EXAMPLE: +
+
+The + +structure + +of + +the + +referred + +Link + +header + +is + +shown + +below. + +The + +first + +component + +(between + +< > +) + +is + +a + +dereferenceable + +URI + +pointing + +to + +the + +JSON-LD + +document + +which + +contains + +the + +@context + +to + +be + +used + +to + +expand + +the + +terms + +used + +by + +the + +corresponding + +operation. + +The + +second + +parameter + +is + +a + +fixed, + +non-dereferenceable + +URI + +used + +to + +denote + +a + +unique + +identifier + +and + +semantics + +for + +this + +header + +(marking + +it + +as + +a + +link + +to + +a + +JSON-LD + +@context +). + +The + +third + +and + +final + +parameter + +flags + +the + +MIME + +type + +of + +the + +linked + +resource + +(JSON-LD). +
+
+
+
+ +
+
+ +
+
+
    +
  • +If the request verb is POST, PATCH or PUT and the Content-Type header is +"application/json", then the +@context shall be obtained from a Link Header as mandated by +JSON-LD [2], section +6.2. In the absence of such Link Header, then the @context shall +be the default @context. In any case, if the request payload body +(as JSON) contains a @context term, then an HTTP error response +of type BadRequestData shall be raised. +
    • +
  • +If the request verb is POST, PATCH or PUT and the Content-Type header is +"application/ld+json", then the +associated @context shall be obtained from the request payload +body itself. If no @context can be obtained from the request +payload body, then an HTTP error response of type BadRequestData +shall be raised. In any case, the presence of a JSON-LD Link header in +the incoming HTTP request when the Content-Type header is "application/ld+json" shall result in an HTTP +error response of type BadRequestData. +
    • +
+

In summary, from a developer's perspective, for POST, PATCH and PUT +operations, if MIME type is "application/ld+json", then the associated +@context shall be provided only as part of the request payload +body. Likewise, if MIME type is "application/json", then the associated +@context shall be provided only by using the JSON-LD Link header. +No mixes are allowed, i.e. mixing options shall result in HTTP response +errors. Implementations should provide descriptive error messages when +these situations arise.

+

In contrast, GET and DELETE operations always take their input +@context from the JSON-LD Link Header.

+

6.3.6 HTTP response common +requirements

+

Implementations shall honour the Accept header provided by HTTP +requests as mandated by clause +6.3.4:

+
    +
  • +If the target response's MIME type is "application/json" such response shall include +a Link to the associated JSON-LD @context as mandated by [2], section 6.2. +
    • +
+
    +
  • +If the Prefer header [26] is set to +"ngsi-ld=<version>" then implementations shall set the +Preference-Applied header to "ngsi-ld=<conformant-version>" in the +returned response indicating which version of the NGSI-LD specification +the payload body conforms to, as mandated in clause +4.3.6.8. +
    • +
+
    +
  • +If the target response's MIME type is "application/ld+json", then the response +payload body provided by the HTTP response shall include a JSON-LD +@context. +
    • +
+
    +
  • +If the Prefer Header [26] is set to +"ngsi-ld=<version>" then implementations shall set +Preference-Applied header to "ngsi-ld=<conformant-version>" in the +returned response indicating which version of the NGSI-LD specification +the payload body conforms to, as mandated in clause +4.3.6.8. +
    • +
+
    +
  • +If the target response's MIME type is "application/geo+json" and the Prefer Header +[26] is omitted or +set to "body=ld+json", then the response +payload body provided by the HTTP response shall include a JSON-LD +@context, and the representation of the entities shall be in +GeoJSON format in the response payload body. +
    • +
  • +If the target response's MIME type is "application/geo+json" and the Prefer Header +[26] is set to "body=json" such response shall include a Link +to the associated JSON-LD @context as mandated by [2], section 6.2 and the +representation of the entities shall be in GeoJSON format in the +response payload body, and @context shall be omitted from the +payload body. +
    • +
+

Operations where the response payload body is not present such as +successful HTTP POST, PATCH, PUT or DELETE operations and all error +responses, do not include the Link header in the response.

+

Operations that result in an error that return a payload or that +result in a partial success (207 Multi-Status) shall always respond with +MIME type "application/json", +regardless of the Accept header. It is assumed that if a client +application understands any of the supported MIME types, the application +shall understand "application/json" +errors. Only Fully Qualified Names shall be used in the payload body of +error or partial success responses, as there is no context present.

+

No Content-Length HTTP header shall be present if the response code +is 204.

+

6.3.7 Representation of Entities

+

For HTTP GET and POST operations corresponding to “Retrieve Entity” +(see clause +5.7.1) and “Query Entities” (see clause +5.7.2), Context Broker +implementations shall support the parameter specified in Table 6.3.7‑1, +which specifies all possible supported representations formats.

+

In contrast, at a minimum, registered Context Source implementations shall +support the normalized representation of Entities as default. When a +registered Context Source is unable +to support additional representations, a 501 Not Implemented Error shall +be raised.

+
+Table 6.3.7-1: Entity representations: format + options parameter +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+When its value is "normalized", a +normalized representation of Entities shall be provided as defined by clause +4.5.1, with Attributes returned in the normalized representation as +defined in clauses 4.5.2.2, +4.5.3.2, +4.5.18.2 +and 4.5.20.2. +
+
+ +
+
+When its value is "concise", a concise +lossless representation of Entities shall be provided as defined by clause +4.5.1. with Attributes returned in the concise representation as +defined in clauses 4.5.2.3, +4.5.3.3, +4.5.18.3 +and 4.5.20.3. +In this case the Context Broker will +return data in the most concise lossless representation possible, for +example removing all Attribute type members. +
+
+ +
+
+When its value is "simplified" (or its +synonym "keyValues"). a simplified +representation of Entities shall be provided as defined by clause +4.5.4 +
+
+ +
+
+If the Accept Header is set to "application/geo+json" the response will be in +simplified GeoJSON format as defined by clause +4.5.17. +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword "normalized", a normalized representation of +Entities shall be provided as defined by clause +4.5.1, with Attributes returned in the normalized representation as +defined in clauses 4.5.2.2, +4.5.3.2, +4.5.18.2 +and 4.5.20.2. +
+
+ +
+
+When its value includes the keyword "concise", a concise lossless representation of +Entities shall be provided as defined by clause +4.5.1. with Attributes returned in the concise representation as +defined in clauses 4.5.2.3, +4.5.3.3, +4.5.18.3 +and 4.5.20.3. +In this case the Context Broker will +return data in the most concise lossless representation possible, for +example removing all Attribute type members. +
+
+ +
+
+When its value includes the keyword "simplified" (or its synonym "keyValues"). a simplified representation of +Entities shall be provided as defined by clause +4.5.4. +
+
+ +
+
+If the Accept Header is set to "application/geo+json" the response will be in +simplified GeoJSON format as defined by clause +4.5.17. +
+

6.3.8 Notification behaviour

+

In the HTTP binding a notification that is triggered by a +subscription shall be sent by issuing an HTTP POST request targeted to +the value of notification.endpoint.uri member of the subscription +structure (defined by clauses 5.2.12, +5.2.14 +and 5.2.15). For +the HTTP binding, the protocol part of the endpoint URI is http or +https. In case the optional MQTT notification binding (clause +7) is supported, the protocol part of the endpoint URI can also be +mqtt or mqtts. The MIME type associated to the POST +request shall be "application/json" by +default. However, this can be changed to "application/ld+json", or "application/geo+json" by means of the +endpoint.accept member.

+

If the target MIME type is "application/json" then the HTTP notification +request shall include a Link header with a reference to the +corresponding JSON-LD @context as mandated by the JSON-LD +specification [2], +section 6.2 (to the default JSON-LD @context if none +available).

+

If the optional array (of KeyValuePair type, as defined by clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new custom HTTP header for each member +named "key" of the key, value pairs that make up the array shall be +generated and included in the HTTP POST's list of headers. The content +of each custom header shall be set equal to the content of the +corresponding "value" member of the KeyValuePair. "Key" and +"value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

If the target MIME type is "application/geo+json" and the +notification.endpoint.receiverInfo member contains a key "Prefer" whose value is set to "body=json" then the HTTP notification request +shall include a Link header with a reference to the corresponding +JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the +default JSON-LD @context if none available).

+

If the target MIME type is "application/geo+json" and the +notification.endpoint.receiverInfo contains a key "Prefer" whose value is set to "body=ld+json" or the "Prefer" key is omitted or +notification.endpoint.receiverInfo does not exist, then the HTTP +notification request includes an @context element in the payload +body.

+

6.3.9 Csource Notification +behaviour

+

In the HTTP binding a csource notification that is triggered by a +csource subscription shall be sent by issuing an HTTP POST request +targeted to the value of notification.endpoint.uri member of the +csource subscription structure (defined by clauses 5.2.12 +and 5.2.14). +The MIME type associated to the POST request shall be "application/json" by default. However, this +can be changed to "application/ld+json" by means of the endpoint.accept +member.

+

If the target MIME type is "application/json" then the HTTP notification +request shall include a Link header with a reference to the +corresponding JSON-LD @context as mandated by the JSON-LD +specification [2], +section 6.2 (to the default JSON-LD @context if none +available).

+

If the optional array (of KeyValuePair type, as defined by clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new custom HTTP Header for each member +named "key" of the key, value pairs that make up the array shall be +generated and included in the HTTP POST's list of headers. The content +of each custom header shall be set equal the content of the +corresponding "value" member of the KeyValuePair. "Key" and +"value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

6.3.10 Pagination behaviour

+

For HTTP operations corresponding to the operations listed in clause +4.12 (see Table +6.2‑1 for a list of HTTP operations with their corresponding +clauses), implementations shall support the HTTP query parameter +specified in Table +6.3.10‑1.

+
+Table 6.3.10-1: Pagination: limit parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Integer +
+0..1 +
+Only values greater or equal to 0. +
+
+It defines the limit to the number of NGSI-LD Elements that shall be +retrieved at a maximum as mandated by clause +5.5.9. The value 0 is only allowed in combination with the +count URI parameter. +
+

This clause defines the specific HTTP binding mechanisms that shall +be used in conjunction with the behaviours defined by clause +5.5.9. Particularly, to flag the existence of related pages that +could be retrieved when dealing with query operations involving +pagination, NGSI-LD Systems implementing the HTTP binding shall use the +HTTP Link header field as mandated by IETF RFC 8288 [7], clause +3, as follows:

+
    +
  • +The pointers to the next and previous pages (when needed as mandated by +clause +5.5.9) shall be serialized as link-value elements. The content of +such link-value(s) shall be: +
    • +
+
    +
  • +For the next page, the Link Target shall be a URI-reference that could +be dereferenced by an NGSI-LD Client to retrieve the next page of +NGSI-LD Elements. In addition, the Link Relation Type shall be equal to +"next", registered under the IANA +Registry of Link Relation Types [20]. +
    • +
  • +For the previous page, the Link Target shall be a URI-reference that +could be dereferenced by an NGSI-LD Client to retrieve the previous page +of NGSI-LD Elements. In addition, the Link Relation Type shall be equal +to "prev", registered under the IANA +Registry of Link Relation Types [20]. +
    • +
+
    +
  • +At least, the "type" Link Target Attribute shall be included by the +previously described serialized Link Header, as mandated by IETF RFC +8288 [7], , and its +value shall be exactly equal to the media type resulting from the +original request made by the NGSI-LD Client (the request that triggered +the current pagination iteration). +
    • +
+
+
+EXAMPLE: +
+
+If + +the + +media + +type + +requested + +originally + +was + +"application/json" + +then + +during + +the + +entire + +pagination + +iteration + +the + +value + +of + +the + +Link + +Target + +Attribute + +"type" + +shall + +be + +"application/json". +
+
+

If the transparent pagination option as described in is used, the +URI-references for the "next" and "prev" link to the next and previous +pages respectively should include the limit parameter as +specified in Table +6.3.10‑1 and the offset parameter as specified in Table 6.3.10‑2, giving the Context Consumer +more control, i.e. to adapt the size of the page using limit and +jump to a desired set of elements in the results using +offset.

+
+Table 6.3.10‑2: Pagination: offset +parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
offsetInteger0..1

Only values greater or equal to 0.

+

It defines the offset of the first NGSI-LD Element that shall be +retrieved from the beginning of the result set. If offset is set to a +value larger than the result set, the offset should be assumed to be +equal to the size of the result set, i.e. only the last element of the +result set is to be returned if there are any results.

+

Temporal representation of resources adds an additional dimension to +the pagination. Depending on the requested time range, the response will +contain multiple instances of the requested Attribute, and therefore an +additional pagination mechanism for those temporal representations is +required, in order to limit the time range of the response. If no limits +are specified, a default limit is enforced, depending on implementation +specific configurations. For HTTP operations on Temporal +Evolutionof Entities, implementations shall use the +Partial Content Response (206) as specified by IETF RFC 7233 [31], clause +4.1, if the implementation is not able to respond with the full +representation at once. In this case, for requests where the parameter +lastN is present, pagination shall happen "backwards" (from the +most recent to the least recent timestamp in the requested time range). +For requests without the parameter lastN, pagination shall happen +"forwards" (from the least recent to the most recent timestamp in the +requested time range).

+

This is achieved by including the "Content-Range" header field with the following +contents:

+
    +
  • +"unit" shall be equal to "DateTime"; +
    • +
  • +"range-start" and "range-end" shall be of type DateTime. +They depend on the requested time relationship timerel (as +defined by clause +4.11), as follows: +
    • +
+
    +
  • +If the lastN parameter is present, pagination shall happen +"backwards": +
    • +
+
    +
  • +"range-start" shall be equal to "timeAt" for requests with +timerel=before, "endTimeAt" for +requests with timerel=between, or the most recent timestamp in +the range of the response, for requests with timerel=after; +
    • +
  • +"range-end" shall be equal to the least +recent timestamp in the range of the response; +
    • +
  • +"size" shall be equal to the requested +lastN. +
    • +
+
    +
  • +If the lastN parameter is not present, +pagination shall happen "forwards": +
    • +
+
    +
  • +"range-start" shall be equal to +timeAt for requests with timerel=after or +timerel=between, or the least recent timestamp in the range of +the response, for requests with timerel=before; +
    • +
  • +"range-end" shall be equal to the most +recent timestamp in the range of the response; +
    • +
  • +"size" shall be equal to "*". +
    • +
+

6.3.11 Including system +Attributes

+

For HTTP GET operations performed over the resources /entities/, +/subscriptions/, /csourceRegistrations/, /csourceSubscriptions/, +/temporal/entities/ and all of its sub-resources, and for HTTP POST +operations corresponding to “Query Entities” (see clause +5.7.2) and “Query Temporal Evolutions of Entities” (see clause +5.7.4), implementations shall support the parameter specified in Table 6.3.11‑1. +Implementations shall not raise an error if they do not hold system +generated temporal attributes.

+
+Table 6.3.11-1: Including system generated temporal attributes: options +parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+options +
+Comma separated list of strings +
+0..1 +
+When its value includes the keyword "sysAttrs", a representation of NGSI-LD +Elements shall be provided so that the system generated temporal +attributes createdAt, modifiedAt and the system temporal +attribute expiresAt are included in the response payload body +where known. In the case of temporal representations, also the system +generated temporal attribute deletedAt is included, if the +NGSI-LD Element has been deleted. +
+

6.3.12 Simplified +or aggregated temporal representation of Entities

+

For HTTP GET and POST operations corresponding to “Retrieve Temporal +Evolution of an Entity” (see clause +5.7.3) and “Query Temporal Evolution of Entities” (see clause +5.7.4), implementations shall support the parameter specified in Table +6.3.12‑1.

+
+Table 6.3.12-1: Temporal Entity representations: format + options +parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+It shall be one of: "temporalValues", +"aggregatedValues". +
+
+ +
+
+When its value is "temporalValues", a +simplified temporal representation of entities shall be provided as +defined by clause +4.5.8. +
+
+ +
+
+When its value is "aggregatedValues", an +aggregated temporal representation of entities shall be provided as +defined by clause +4.5.19. +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword "temporalValues", a simplified temporal +representation of entities shall be provided as defined by clause +4.5.8. +
+
+ +
+
+When its value includes the keyword "aggregatedValues", an aggregated temporal +representation of entities shall be provided as defined by clause +4.5.19. +
+
+ +
+
+Only one of the two keywords can be present in the values of the +parameter. +
+
+ +
+
+If both format and options are present, the value of the +format parameter shall take precedence. +
+

6.3.13 Counting number of results

+

This clause implements the behaviour described in clause +4.13, in case of HTTP binding.

+

For HTTP operations corresponding to the operations listed in clause +4.12 (see Table +6.2‑1 for a list of HTTP operations with their corresponding +clauses), implementations shall support the HTTP query parameter +specified in Table +6.3.13‑1.

+
+Table 6.3.13-1: Counting number of results: count parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+count +
+Boolean +
+0..1 +
+If true, then a special HTTP header (NGSILD-Results-Count) is set +in the response. Regardless of how many entities are actually returned +(maybe due to the limit URI parameter), the total number of +matching results (e.g. number of Entities) is returned. +
+

This clause defines the specific HTTP binding mechanisms that can be +useful to plan the limit and offset URI parameters for +pagination, thus allowing to convey an overview of the number of +entities in a system.

+

To get only the count itself, and no entities, the URI parameter +limit may have the value "0", and +an empty array shall be returned as payload body.

+

Setting the URI parameter limit to zero without including the +count URI parameter will result in a 400 BadRequest +error.

+

6.3.14 Tenant +specification

+

If the system implementing the NGSI-LD API supports multi-tenancy as +described in clause +4.14 and clause +5.5.10, the Tenant, to which the +NGSI-LD HTTP operation is targeted, is specified as the HTTP header +"NGSILD-Tenant", +whose value is the String identifying the Tenant. In case the target Tenant is the default Tenant, the HTTP header is omitted. If the +HTTP header "NGSILD-Tenant" is +present in the HTTP request, it shall also be present in HTTP response. +This also applies to HTTP notifications sent as a result of +subscriptions with an "NGSILD-Tenant" HTTP +header (clause +6.3.8).

+

6.3.15 GeoJSON +representation of spatially bound entities

+

For HTTP GET and POST operations corresponding to “Retrieve Entity” +(see clause +5.7.1) and “Query Entities” (see clause +5.7.2), if the GeoJSON Accept header ("application/geo+json") is present, +implementations shall render the entities of the response in the GeoJSON +format, as described in clause +5.2.29.

+

For GeoJSON representations, a GeoProperty may be selected as +the geolocation to be used as the geometry within the GeoJSON payload. +If no geometryProperty parameter is specified, then the +location GeoProperty of the Entity is used.

+
+Table 6.3.15-1: Selecting a geometry +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+geometryProperty +
+String +
+0..1 +
+If not present, "location" is used. +
+datasetId +
+String +
+0..1 +
+Shall be valid URI. If the referenced GeoProperty consists of an +attribute with multiple instances the datasetId specifies which +instance of the value is to be selected. If not present, the default +instance is used. +
+

6.3.16 Expiration time for +cached @contexts

+

Implementations shall comply with the Expires header field (section +5.3 of IETF RFC 7234 [30]) or a max-age or s-maxage +response directive of Cache-Control header field (section 5.2.2 of IETF +RFC 7234 [30]) that +may be present in the downloaded @context. This means that +implementations shall periodically invalidate the "Cached" @contexts according to the +headers mentioned above. Since origin servers do not always provide +explicit expiration times, implementations should assign a heuristic +(for instance according to IETF RFC 7234 [30] section 4.2.2) expiration +time when an explicit time is not specified.

+

6.3.17 Distributed +Operations Caching and Timeout Behaviour

+

The caching of response data received from forwarded HTTP GET +requests is optionally supported by Context +Brokers. For HTTP GET operations performed over the resources +/entities and /entities/{entity-id}, where a Context Source Registration matches the +request and a previous forwarded response has been cached and a +subsequent request occurs before the Context +Source Registration cacheDuration (as defined in Table +5.2.34‑1) has been reached, the result may incorporate data cached +from a previous response. To indicate that +data from a cache has been included in the response, the HTTP header +"NGSILD-Warning" shall be included. The +value shall match the IANA Warning Code [32] 110 - Response is +Stale.

+

"NGSILD-Warning" HTTP headers shall +also be used to indicate instances of abnormal behaviour for distributed +HTTP GET operations performed over the resources /entities and +/entities/{entity-id}.

+
+Table 6.3.17-1: NGSI-LD Warning Codes +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+IANA Warning Code +
+Remarks +
+110 - Response is Stale +
+No request was made to a specified registration endpoint - data from a +cached value has been reused and it has been incorporated into the +response. +
+111 - Revalidation Failed +
+Although data was received from the registration endpoint within the +specified timeout period, the payload of the response was invalid. This +could occur if the payload was corrupted or a non-NGSI payload was +received. +
+199 - Miscellaneous Warning +
+No response was received from the registration endpoint within the +specified timeout period or a registration loop has been detected. +
+299 - Miscellaneous Persistent Warning +
+An error response (such as 403 - Forbidden) was +received from the registration endpoint within the specified timeout +period. This could occur if the Context +Broker has insufficient access rights to retrieve the data. +
+

For distributed HTTP GET operations, registered context sources +should always respond with a valid NGSI-LD payload. The Context Broker shall successfully parse +this data and invalid non-NGSI-LD payloads shall be rejected and not +incorporated into the overall response. It should be noted that a +registration endpoint responding with no data and the HTTP status code +404 - Not Found should not be considered as abnormal +behaviour for distributed operations.

+

For all other operations, which correspond to HTTP Unsafe methods, +the error response should be as informative as possible.

+

In the case of an exclusive or +redirect registration, where all of the data is held +outside of the Context Broker and +held in a single registered source, the following errors shall be +returned:

+
    +
  • +508 Loop Detected – if the single registered source and tenant is +registered to redirect back on to the Context Broker. +
    • +
  • +504 Gateway Timeout - if the single registered source fails to respond +in time. +
    • +
  • +404 Not Found - if resources not found within the single registered +source. +
    • +
  • +502 Bad Gateway - if the single forwarded request fails for any other +reason such as the Context Broker +itself having insufficient access rights. +
    • +
+

In the case of an inclusive or +redirect registration, where an entity is distributed +over multiple equally valid endpoints, but when updating the state of +the distributed entity, an error response is returned from one or more +registered sources:

+
    +
  • +207 Multi Status. +
    • +
+

In the case of an auxiliary registration HTTP unsafe +methods are not supported.

+

Whenever failures or timeouts occur, Context Brokers may optionally decline to +make subsequent requests to the same registration endpoint until the +cooldown period (as defined in +Table 5.2.9-1) has been reached.

+

6.3.18 Limiting Distributed +Operations

+

The parameter described in this clause limits the execution of an +operation to a local Context Source or Context Broker (clause +5.5.13). It amends the matching Context +Source Registrations behaviour as described in , in the case of +the HTTP binding in order to avoid cascading distributed operations (see +clause +4.3.6.4). For all operations the resources /entities/, /types/, +/attributes/, /entityOperations/, /temporal/entities/ and +temporal/entityOperations/ (and their respective child resources) +implementations shall support the HTTP query parameter specified in Table 6.3.18‑1. +The Registry API operations are always local and thus are not included +here.

+
+Table 6.3.18-1: Limiting distributed operations: local parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+local +
+Boolean +
+0..1 +
+If local=true then no Context Source +Registrations shall be considered as matching to avoid cascading +distributed operations (see clause +4.3.6.4) +
+
+ +
+

Furthermore, to avoid infinite loops, for all operations, the +resources /entities/, /types/, /attributes/, /subscriptions/, +/csourceSubscriptions/, /entityOperations/, /temporal/entities/ and +temporal/entityOperations/ implementations shall fully support the HTTP +Via Header (IETF RFC 7230 [27]) as specified in Table 6.3.18‑2. +AnyContext Broker implementation +passing a distributed operation request onward to another Context Source shall send an additional +field value on the Via header field using its own unique Context Source hostAlias (see clause +5.2.40) as the pseudonym.

+
+Table 6.3.18-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+Via +
+String as defined in IETF RFC 7230 [27] +
+0..1 +
+If present, the listing of previously encountered Context Sources supplied is used when +determining matching registrations +
+

6.3.19 Extra +information to provide when contacting Context Source

+

As specified in clauses 4.3.6.5 +and 4.3.6.6, +extra information to be provided when contacting a Context Source can be specified in the +optional array (of KeyValuePair type, as defined by clause +5.2.22) contextSourceInfo of the CSourceRegistration.

+

In the HTTP binding, if the "jsonldContext" key is present, the URL value +is placed in an HTTP Link Header as described by the JSON-LD +specification [2], +section 6.2 and, whenever a payload body is present in the request, the +HTTP Content-Type Header is set to "application/json". For all other keys, a new +custom HTTP header is added for each member named "key" of the key-value +pairs that make up the array shall be generated and included in the HTTP +list of headers. The content of each custom header shall be set equal to +the content of the corresponding "value" member of the +KeyValuePair, unless the special value "urn:ngsi-ld:request" has been set, in which +case the value is to be taken from the triggering request, if present +there. "Key" and "value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

Headers derived from other elements of the CSourceRegistration, e.g. +"NGSILD-Tenant", +take precedence and cannot be overridden using contextSourceInfo. +The same applies for headers generally set by HTTP itself, e.g. +Content-length.

+

6.3.20 Invalid +parameters

+

If an HTTP request for an operation contains parameters that are +incompatible with the operation, or it contains values of the +options parameter that are not supported by the operation, an +HTTP error response of type InvalidRequest should be +returned.

+

6.3.21 +Optional profile information regarding versioning and datatype +conformance

+

In the HTTP Binding, if an HTTP Link header with a profile +parameter in accordance with IETF RFC 6906 [33], is found set to +<https://uri.etsi.org/ngsi-ld/profile/version> +then implementations that are only partially capable of interpreting the +datatypes conformant to the supplied NGSI-LD version may use this +information to allow the payload to be accepted within the constraints +of the current implementation (see clause +5.5.4) through amending the payload body and applying the fallbacks +defined within clause +4.3.6.8.

+

6.4 Resource: +entities/

+

6.4.1 Description

+

This resource represents the entities known to an NGSI-LD system.

+

6.4.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/ +
    • +
+

6.4.3 Resource +methods

+

6.4.3.1 POST

+

This method is bound to the operation "Create Entity" and shall +exhibit the behaviour defined by clause +5.6.1, taking the entity to be created from the HTTP request payload +body. Figure +6.4.3.1‑1 shows the Create Entity interaction and Table 6.4.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.4.3.1-1: Create Entity interaction +
+
+Table 6.4.3.1-1: Post Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the entity that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +member should convey more information about the error. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the entity or an exclusive or redirect +registration defining the entity already exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable Entity +
+It is used to indicate that the operation is not available, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.4.3.2 GET

+

This method is associated to the operation "Query Entities" and shall +exhibit the behaviour defined by clause +5.7.2, providing entities as part of the HTTP response payload body. +In addition to this method, an alternative way to perform "Query +Entities" operations via POST is defined in clause +6.23. Figure +6.4.3.2‑1 shows the query entities interaction.

+
+ +
+
+Figure 6.4.3.2-1: Query Entities interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.4.3.2‑1, +the request headers that shall be supported by implementations are those +defined in Table +6.4.3.2‑2 and Table 6.4.3.2‑3 +describes the request body and possible responses.

+
+Table 6.4.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved. +
+type +
+String +

0..1

+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Selection of Entity Types as per clause +4.17. "*" is +also allowed as a value and local is implicitly set to +true and shall not be explicitly set tofalse. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids. +
+attrs +
+Comma separated list of strings +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be matched by the Entities and also included in +the response, i.e. only Entities that contain at least one of the +Attributes in attrs are to be included in the response, and only +the Attributes listed in attrs are to be included in each of the +Entities of the response. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or a +projected Attribute name). +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or a +projected Attribute name). +
+
+When defined, the listed Entity members are removed from each Entity +within the payload. +
+q +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Query as per clause +4.9. +
+expandValues +
+Comma separated list of strings +
+0..1 +
+
+ +
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes whose values shall be expanded into URIs according to +the supplied @context prior to executing a query. It is part of +query. +
+jsonKeys +
+Comma separated list of strings +
+0..1 +
+
+ +
+Each String is an Attribute (Property or Relationship) name. +
+
+Values of the identified attributes are to be considered uninterpretable +as JSON-LD and should not be expanded against the supplied +@context using JSON-LD type coercion prior to executing the +query. +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9. +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present. At +least one among: type, attrs, q, or geometry +shall be present, unless the execution of the request is limited to +local scope (see clause +5.5.13). +
+Geometry as per clause +4.10. It is part of geoquery. +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present. +
+Geo relationship as per clause +4.10. It is part of geoquery. +
+coordinates +
+String +
+0..1 +
+
+It shall be one if geometry or georel are present. +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery. +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored unless a geoquery is present. +
+It represents the name of the Property that contains the +geospatial data that will be used to resolve the geoquery. By default, +will be location (see clause +4.7). +
+geometryProperty +
+String +
+0..1 +
+It represents a Property name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the toplevel geometry field. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19). +
+containedBy +
+Comma separated list of URIs +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. Only applicable if joinLevel is +present. +
+join +
+String +
+0..1 +
+The type of Linked Entity retrieval +to apply (see clause +4.5.23). Allowed values: "flat", +"inline", "@none". +
+joinLevel +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. +
+
+Only applicable if join parameter is present. +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" for including the default Attribute +instances. Specifies the datasetIds of the Attribute instances to be +selected for each matched Attribute as per clause +4.5.5. +
+entityMap +
+Boolean +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response. +
+entityMapLifetime +
+String +
+0..1 +
+Suggested duration, represented in ISO 8601 format [17], for which the requester +wants the EntityMap to exist. The actual expiresAt time of the EntityMap +shall be set by the Context Broker or Context Source, possibly +overriding the requested duration.Only applicable if entityMap is +set to true. +
+splitEntities +
+Boolean +
+0..1 +
+If true it is assumed that single Entities are distributed +between different Context Brokers and/or Context Sources and this has to +be taken into account when applying any kind of filters (q, geoQ, +scopeQ, Attributes etc.). If false it is expected that Context +Broker and/or Context Source always have complete Entities, which allows +applying filters locally. +
+
+The parameter does not apply in case local is true. +
+
+The default value should be decided by implementation; it should be +configurable. +
+
+Table 6.4.3.2-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+NGSILD-EntityMap +
+URI +
+0..1 +
+If present, the EntityMap supplied is used for determining the set of +Entities requested during the query operation. The location of the +EntityMap used in the query operation is returned in the response. +
+
+Table 6.4.3.2-3: Get Entities request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity[] +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +
+A response body containing the query result as a list of entities, +unless the Accept Header indicates that the Entities are to be rendered +as GeoJSON. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource used in the +operation. +
+Entity[] +
+1 +
+203 Non-Authoritative Information +
+As above, but returning an altered response +body, amended to conform to a specific version of the NGSI-LD +specification as mandated in clause +4.3.6.8. +
+
+ +
+
+The response shall also include a "Preference-Applied" HTTP header set +to "ngsi-ld=<conformant-version>". +
+GeoJSON FeatureCollection +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +
+If the Accept Header indicates that the Entities are to be rendered as +GeoJSON, a response body containing the query result as GeoJSON +FeatureCollection is returned. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource used in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+ +
+
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Registered Context Sources +to indicate that the data format of the request is unsupported see clause +6.3.7. +
+

6.4.3.3 DELETE

+

This method is associated to the operation "Purge Entities" and shall +exhibit the behaviour defined by clause +5.6.21, providing entities as part of the HTTP response payload +body. Figure 6.4.3.3‑1 shows the query +entities interaction.

+
+ +
+
+Figure 6.4.3.3‑1: +Purge Entities interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.4.3.3‑1, +the request headers that shall be supported by implementations are those +defined in Table +6.4.3.3‑2 and Table 6.4.3.3‑3 +describes the request body and possible responses.

+
+Table 6.4.3.3-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved. +
+type +
+String +

0..1

+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Selection of Entity Types as per clause +4.17. “*” is also allowed as a value and local is implicitly +set to true and shall not be explicitly set to false. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids. +
+drop +
+Comma separated list of strings +
+0..1 +
+Each String is an Attribute name. +
+
+When defined, every Entity within the payload body is reduced to not +contain the listed Entity members. +
+keep +
+Comma separated list of strings +
+0..1 +
+Each String is an Attribute name. +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+q +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Query as per clause +4.9. +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9. +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present. At +least one among: type, attrs, q, or geometry +shall be present, unless the execution of the request is limited to +local scope (see clause +5.5.13). +
+Geometry as per clause +4.10. It is part of geoquery. +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present. +
+Geo relationship as per clause +4.10. It is part of geoquery. +
+coordinates +
+String +
+0..1 +
+
+It shall be one if geometry or georel are present. +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery. +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored unless a geoquery is present. +
+It represents the name of the Property that contains the +geospatial data that will be used to resolve the geoquery. By default, +will be location (see clause +4.7). +
+geometryProperty +
+String +
+0..1 +
+It represents a Property name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the toplevel geometry field. +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19). +
+
+Table 6.4.3.3-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+NGSILD-EntityMap +
+URI +
+0..1 +
+If present, the EntityMap supplied is used for determining the set of +Entities requested during the purge operation. The location of the +EntityMap used in the purge operation is returned in the response +
+
+Table 6.4.3.3-3: Purge Entities request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.5 Resource: +entities/{entityId}

+

6.5.1 Description

+

This resource represents an entity known to an NGSI-LD system.

+

6.5.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.5.2‑1.

+
+Table 6.5.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the entity to be retrieved +
+

6.5.3 Resource +methods

+

6.5.3.1 GET

+

This method is associated to the operation "Retrieve Entity" and +shall exhibit the behaviour defined by clause +5.7.1. The Entity identifier is the value of the resource URI +variable "entityId". Figure 6.5.3.1‑1 +shows the retrieve entity interaction.

+
+ +
+
+Figure 6.5.3.1-1: Retrieve Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.1‑1, +the request headers that shall be supported by implementations are those +defined in Table +6.5.3.1‑2 and Table 6.5.3.1‑3 +describes the request body and possible responses.

+
+Table 6.5.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+attrs +
+Comma separated list of strings +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be matched by the Entity and included in the +response. If the Entity does not have any of the Attributes in +attrs, then a 404 Not Found shall be retrieved. If +attrs is not specified, no matching is performed and all +Attributes related to the Entity shall be retrieved. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or a +projected Attribute name). When defined, every Entity within the payload +body is reduced down to only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or a +projected Attribute name). When defined, the listed Entity members are +removed from each Entity within the payload. +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17. +
+geometryProperty +
+String +
+0..1 +
+It represents a GeoProperty name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the "geometry" element. By default, it +shall be location. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+containedBy +
+Comma separated list of URIs +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. Only applicable if joinLevel is +present. +
+join +
+String +
+0..1 +
+The type of Linked Entity retrieval +to apply (see clause +4.5.23). Allowed values: "flat", +"inline", "@none" . +
+joinLevel +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. Default is 1 +
+
+Only applicable if join parameter is: "flat" or "inline". +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+entityMap +
+Boolean +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response. +
+
+Table 6.5.3.1-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+NGSILD-EntityMap +
+URI +
+0..1 +
+If present, the EntityMap supplied is used for determining the extent of +the Entity data requested during the retrieval operation. The location +of the EntityMap used in the retreieval operation is returned in the +response. +
+
+Table 6.5.3.1-3: Get Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +entity which consists only of the selected Attributes, unless the Accept +Header indicates that the Entity is to be rendered as GeoJSON. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource used in the +operation. +
+Entity +
+1 +
+203 Non-Authoritative Information +
+As above, but returning an altered response +body, amended to conform to a specific version of the NGSI-LD +specification as mandated in clause +4.3.6.8. +
+
+ +
+
+The response shall also include a "Preference-Applied" HTTP header set +to "ngsi-ld=<conformant-version>". +
+GeoJSON Feature +
+1 +
+200 OK +
+If the Accept Header indicates that the Entity is to be rendered as +GeoJSON, a GeoJSON Feature is returned. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource used in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Registered Context +Sources to indicate that the data format of the request is +unsupported see clause +6.3.7. +
+

6.5.3.2 DELETE

+

This method is associated to the operation "Delete Entity" and shall +exhibit the behaviour defined by . The Entity identifier is the value of +the resource URI variable "entityId". Figure 6.5.3.2‑1 +shows the delete entity interaction.

+
+ +
+
+Figure 6.5.3.2-1: Delete Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.2‑1 +and Table +6.5.3.2‑2 describes the request body and possible responses.

+
+Table 6.5.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.5.3.2-2: Delete Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.5.3.3 PUT

+

This method is bound to the "Replace Entity" operation and shall +exhibit the behaviour defined by clause +5.6.18. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.5.3.3‑1 +shows the Replace Entity interaction.

+
+ +
+
+Figure 6.5.3.3-1: Replace Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.3‑1 +and Table +6.5.3.3‑2 describes the request body and possible responses.

+
+Table 6.5.3.3-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.5.3.3-2: Replace Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Entity to be +replaced. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+The entity was replaced successfully. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

6.5.3.4 PATCH

+

This method is bound to the "Merge Entity" operation and shall +exhibit the behaviour defined by clause +5.6.17. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.5.3.4‑1 +shows the Merge Entity interaction.

+
+ +
+
+Figure 6.5.3.4-1: Merge Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.4‑1 +and Table +6.5.3.4‑2 describes the request body and possible responses.

+
+Table 6.5.3.4-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+It shall be one of: "simplified" (or its +synonym "keyValues"). Where present it +indicates that a simplified representation of Entities has been provided +as defined by clause +4.5.4 +
+
+ +
+
+In this case, when a merge operation applies to an existing Attribute +the type field of the Attribute shall remain unchanged (any +attempt to modify the type of an +
+
+Attribute shall result in a BadRequest error). +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword"simplified" (or its synonym "keyValues"), this indicates that a simplified +representation of Entities has been provided as defined by clause +4.5.4. +
+
+ +
+
+If both format and options are present, the value of the +format parameter shall take precedence. +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+observedAt +
+String +
+0..1 +
+It shall be a DateTime (see clause +4.6.3). +
+
+When a merge operation applies to a pre-existing Attribute which +previously contained an observedAt sub-attribute, the value held +in this query parameter shall be used if no specific observedAt +sub-Attribute is found in the payload body. +
+lang +
+String +
+0..1 +
+It represents the natural language of data held in the request. +
+
+When a merge operation applies to a pre-existing LanguageProperty +and the value is supplied as a string or string array in the payload +body, this query parameter shall be used to determine the key within the +languageMap JSON Object to update. +
+
+Table 6.5.3.4-2: Merge Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be merged. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were merged successfully. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

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

+

6.6.1 Description

+

This resource represents all the Attributes (Properties or +Relationships) of an NGSI-LD Entity.

+

6.6.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId}/attrs +
    • +
+

Resource URI variables for this resource are defined in Table 6.6.2‑1.

+
+Table 6.6.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+

6.6.3 Resource +methods

+

6.6.3.1 POST

+

This method is bound to the "Append Attributes" operation and shall +exhibit the behaviour defined by clause +5.6.3. The Entity identifier is the value of the resource URI +variable "entityId". The data to be appended shall be contained in the +HTTP request payload body. Figure 6.6.3.1‑1 +shows the Append Attributes interaction.

+
+ +
+
+Figure 6.6.3.1-1: Append Attributes interaction +
+

The query parameters that shall be supported are those defined in Table 6.6.3.1‑1 +and Table +6.6.3.1‑2 describes the request body and possible responses.

+
+Table 6.6.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+options +
+Comma separated list of strings +
+0..1 +
+"noOverwrite" indicates that no attribute +overwrite shall be performed. +
+
+Table 6.6.3.1-2: Post Attributes request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be added. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were appended successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+Only the Attributes included in the response payload body were +successfully appended. +
+
+ +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.6.3.2 PATCH

+

This method is bound to the "Update Attributes" operation and shall +exhibit the behaviour defined by clause +5.6.2. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.6.3.2‑1 +shows the Update Attributes interaction.

+
+ +
+
+Figure 6.6.3.2-1: Update Attributes interaction +
+

The query parameters that shall be supported are those defined in Table 6.6.3.2‑1 +and Table +6.6.3.2‑2 describes the request body and possible responses.

+
+Table 6.6.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+Table 6.6.3.2-2: Patch Attributes request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were updated successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+Only the Attributes included in the response payload body were +successfully updated. If no Attributes were successfully updated the +updated array of UpdateResult (see clause +5.2.18) will be empty. +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

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

+

6.7.1 Description

+

This resource represents an attribute (Property or Relationship) of +an NGSI-LD Entity.

+

6.7.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId}/attrs/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.7.2‑1.

+
+Table 6.7.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+

6.7.3 Resource +methods

+

6.7.3.1 PATCH

+

This method is bound to the "Partial Attribute Update" operation and +shall exhibit the behaviour defined by clause +5.6.4. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". The Entity Fragment shall be contained in the HTTP +request payload body. Figure 6.7.3.1‑1 +shows the Partial Attribute Update interaction.

+
+ +
+
+Figure 6.7.3.1-1: Partial Attribute Update interaction +
+

The query parameters that shall be supported are those defined in Table 6.7.3.1‑1 +and Table +6.7.3.2‑2 describes the request body and possible responses.

+
+Table 6.7.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+Table 6.7.3.1-2: Partial Attribute Update request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing the elements of the attribute to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The attribute was updated successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier or attribute name +not known to the system, see clause 6.3.2. +
+

6.7.3.2 DELETE

+

This method is associated to the operation "Delete Attribute" and +shall exhibit the behaviour defined by clause +5.6.5. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". Figure 6.7.3.2‑1 +shows the Delete Attribute interaction, Table 6.7.3.2‑1 +shows the delete parameters to be supported and Table 6.7.3.2‑2 +describes the request body and possible responses.

+
+ +
+
+Figure 6.7.3.2-1: Delete Attribute interaction +
+
+Table 6.7.3.2-1: Delete parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+deleteAll +
+Boolean +
+0..1 +
+If true, all attribute instances are deleted. Otherwise (default) +only the Attribute instance specified by the datasetId is +deleted. In case neither the deleteAll flag nor a datasetId is +present, the default Attribute instance is deleted. +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17. +
+datasetId +
+String +
+0..1 +
+Shall be a valid URI. Specifies the datasetId of the dataset to +be deleted. +
+
+Table 6.7.3.2-2: Delete Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) or +attribute name not known to the system. see clause 6.3.2. +
+

6.7.3.3 PUT

+

This method is bound to the "Replace Attribute" operation and shall +exhibit the behaviour defined by clause +5.6.19. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". The Attribute Fragment shall be contained in the HTTP +request payload body. Figure 6.7.3.3‑1 +shows the Replace Attribute interaction.

+
+ +
+
+Figure 6.7.3.3-1: Replace Attribute interaction +
+

The query parameters that shall be supported are those defined in Table 6.7.3.3‑1 +and Table +6.7.3.3‑2 describes the request body and possible responses.

+
+Table 6.7.3.3-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.7.3.3-2: Replace Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Attribute Fragment +
+1 +
+Attribute Fragment replacing the previous data. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The attribute was replaced successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier or attribute name +not known to the system, see clause 6.3.2. +
+

6.8 Resource: +csourceRegistrations/

+

6.8.1 Description

+

This resource represents the context source registrations known to an +NGSI-LD system.

+

6.8.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceRegistrations/ +
    • +
+

6.8.3 Resource +methods

+

6.8.3.1 POST

+

This method is bound to the operation "Register Context Source" and +shall exhibit the behaviour defined by clause +5.9.2, taking the context source registration to be created from the +HTTP request payload body. Figure 6.8.3.1‑1 +shows the Register Context Source interaction and Table 6.8.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.8.3.1-1: Register Context Source interaction +
+
+Table 6.8.3.1-1: Patch Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+CSourceRegistration +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created context source registration resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the context source registration already +exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable +
+
+Context Source Registration +
+It is used to indicate that the operation is not available see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.8.3.2 GET

+

This method is associated to the operation "Query Context Source +Registrations" and shall exhibit the behaviour defined by clause +5.10.2, i.e. the parameters in the request describe entity related +information, but instead of directly providing this entity information, +the context source registration data, which describes context sources +that can possibly provide the information, are returned as part of the +HTTP response payload body. Figure 6.8.3.2‑1 +shows the Query Context Source Registrations interaction.

+
+ +
+
+Figure 6.8.3.2-1: Query Context Source Registrations interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.8.3.2‑1 +and Table +6.8.3.2‑2 describes the request body and possible responses.

+
+Table 6.8.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved. +
+type +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Selection of Entity Types as per clause +4.17. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids satisfying the +query +
+attrs +
+Comma separated list strings +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes (Properties or Relationships) to be retrieved. +
+q +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Query as per clause +4.9. +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9. +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present. +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Geometry as per clause +4.10. It is part of geoquery. +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present. +
+Geo relationship as per clause +4.10. It is part of geoquery. +
+coordinates +
+String +
+0..1 +
+
+It shall be one if geometry or georel are present. +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery. +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored if no geoquery is present. +
+It represents the name of the Property that contains the geospatial data +that will be used to resolve the geoquery. +
+timeproperty +
+String +
+0..1 +
+
+It shall be ignored if no temporal query is present. +
+It represents a Temporal Property name. +
+
+ +
+
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8). +
+timerel +
+String +
+0..1 +
+It represents the temporal relationship as defined by clause +4.1. +
+
+ +
+
+Allowed values: "before", "after", "between". +
+timeAt +
+String +
+0..1 +
+It represents the timeAt parameter as defined by clause +4.1. +
+
+ +
+
+It shall be a DateTime. Cardinality shall be 1 if timerel +is present. +
+endTimeAt +
+String +
+0..1 +
+It represents the endTimeAt parameter as defined by clause +4.1. +
+
+ +
+
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between". +
+geometryProperty +
+String +
+0..1 +
+It represents a Property name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the toplevel geometry field. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+ +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19). +
+
+Table 6.8.3.2-2: Get Context Source Registrations request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+CSourceRegistration[] +
+1 +
+200 OK +
+A response body containing the query result as an array of context +source registrations. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.9 Resource: +csourceRegistrations/{registrationId}

+

6.9.1 Description

+

This resource represents the context source registration, identified +by registrationId, known to an NGSI-LD system.

+

6.9.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceRegistrations/{registrationId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.9.2‑1.

+
+Table 6.9.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+registrationId +
+Id (URI) of the context source registration +
+

6.9.3 Resource +methods

+

6.9.3.1 GET

+

This method is associated with the operation "Retrieve Context Source +Registration" and shall exhibit the behaviour defined by clause +5.10.1. The registration identifier is the value of the resource URI +variable "registrationId". Figure 6.9.3.1‑1 +shows the Retrieve Context Source Registration interaction and Table 6.9.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.1-1: Retrieve Context Source Registration interaction +
+
+Table 6.9.3.1-1: Get Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+CSourceRegistration +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +context source registration. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier (URI) not known to the system, see clause 6.3.2. +
+

6.9.3.2 PATCH

+

This method is bound to the "Update Context Source Registration" +operation and shall exhibit the behaviour defined by clause +5.9.3. The context source registration identifier is the value of +the resource URI variable "registrationId". The context source +registration to be updated shall be contained in the HTTP request +payload body. Figure 6.9.3.2‑1 +shows the Update Context Source Registration interaction and Table 6.9.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.2-1: Update Context Source Registration interaction +
+
+Table 6.9.3.2-1: Patch Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+CSourceRegistration Fragment +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration that is to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The context source registration was successfully updated. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier not known to the system, see clause 6.3.2. +
+

6.9.3.3 DELETE

+

This method is associated to the operation "Delete Context Source +Registration" and shall exhibit the behaviour defined by clause +5.9.4. The context source registration identifier is the value of +the resource URI variable "registrationId". Figure 6.9.3.3‑1 +shows the Delete Context Source Registration interaction and Table 6.9.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.3-1: Delete Context Source Registration interaction +
+
+Table 6.9.3.3-1: Delete Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier (URI) not known to the system, see clause 6.3.2. +
+

6.10 Resource: +subscriptions/

+

6.10.1 Description

+

This resource represents the subscriptions known to an NGSI-LD +system.

+

6.10.2 Resource +definition

+

Resource URI:

+
    +
  • +/subscriptions/ +
    • +
+

6.10.3 Resource +methods

+

6.10.3.1 POST

+

This method is bound to the operation "Create Subscription" and shall +exhibit the behaviour defined by clause +5.8.1, taking the subscription to be created from the HTTP request +payload body. Figure +6.10.3.1‑1 shows the Create Subscription interaction and Table 6.10.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.10.3.1-1: Create Subscription interaction +
+
+Table 6.10.3.1-1: Post Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the subscription that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created subscription resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the subscription already exists see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.10.3.2 GET

+

This method is associated to the operation "Query Subscriptions" and +shall exhibit the behaviour defined by clause +5.8.4, providing the subscription data as part of the HTTP response +payload body. Figure +6.10.3.2‑1 shows the Query Subscriptions interaction.

+
+ +
+
+Figure 6.10.3.2-1: Query Subscriptions interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.10.3.2‑1 +and Table +6.10.3.2‑2 describes the request body and possible responses.

+
+Table 6.10.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Number +
+0..1 +
+Maximum number of subscriptions to be retrieved +
+
+Table 6.10.3.2-2: Get Subscriptions request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription[] +
+1 +
+200 OK +
+A response body containing a list of subscriptions. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.11 Resource: +subscriptions/{subscriptionId}

+

6.11.1 Description

+

This resource represents a subscription known to an NGSI-LD +system.

+

6.11.2 Resource +definition

+

Resource URI:

+
    +
  • +/subscriptions/{subscriptionId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.11.2‑1.

+
+Table 6.11.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+subscriptionId +
+Id (URI) of the concerned subscription +
+

6.11.3 Resource +methods

+

6.11.3.1 GET

+

This method is associated to the operation "Retrieve Subscription" +and shall exhibit the behaviour defined by clause +5.8.3. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.1‑1 shows the Retrieve Subscription interaction and Table 6.11.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.1-1: Retrieve Subscription interaction +
+
+Table 6.11.3.1-1: Get Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +subscription. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.11.3.2 PATCH

+

This method is associated to the operation "Update Subscription" and +shall exhibit the behaviour defined by clause +5.8.2. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.2‑1 shows the Update Subscription interaction and Table 6.11.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.2-1: Update Subscription interaction +
+
+Table 6.11.3.2-1: Patch Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription Fragment +
+1 +
+Subscription Fragment including id, type and any other subscription +field to be changed +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.11.3.3 DELETE

+

This method is associated to the operation "Delete Subscription" and +shall exhibit the behaviour defined by clause +5.8.5. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.3‑1 shows the Delete Subscription interaction and Table 6.11.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.3-1: Delete Subscription interaction +
+
+Table 6.11.3.3-1: Delete Subscription request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.12 Resource: +csourceSubscriptions/

+

6.12.1 Description

+

This resource represents the context source registration +subscriptions known to an NGSI-LD system.

+

6.12.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceSubscriptions/ +
    • +
+

6.12.3 Resource +methods

+

6.12.3.1 POST

+

This method is bound to the operation "Create Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.2, taking the context source registration subscription to be +created from the HTTP request payload body. Figure +6.12.3.1‑1 shows the Create Context Source Registration Subscription +interaction and Table 6.12.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.12.3.1-1: Create Context Source Registration Subscription +interaction +
+
+Table 6.12.3.1-1: Post Context Source Registration Subscription request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration subscription that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created context source registration subscription +resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the context source registration subscription +already exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.12.3.2 GET

+

This method is associated to the operation "Query Context Source +Registration Subscriptions" and shall exhibit the behaviour defined by +clause +5.11.5, providing the context source registration subscription data +as part of the HTTP response payload body. Figure +6.12.3.2‑1 shows the Query Context Source Registration Subscriptions +interaction.

+
+ +
+
+Figure 6.12.3.2-1: Query Context Source Registration Subscriptions +interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.12.3.2‑1 +and Table +6.12.3.2‑2 describes the request body and possible responses.

+
+Table 6.12.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Number +
+0..1 +
+Maximum number of subscriptions to be retrieved +
+
+Table 6.12.3.2-2: Get Context Source Registration Subscriptions request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription[] +
+1 +
+200 OK +
+A response body containing a list of context source registration +subscriptions. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.13 Resource: +csourceSubscriptions/{subscriptionId}

+

6.13.1 Description

+

This resource represents the context source registration +subscription, identified by subscriptionId, known to an NGSI-LD +system.

+

6.13.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceSubscriptions/{subscriptionId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.13.2‑1.

+
+Table 6.13.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+subscriptionId +
+Id (URI) of the concerned context source registration subscription +
+

6.13.3 Resource +methods

+

6.13.3.1 GET

+

This method is associated to the operation "Retrieve Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.4. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.1‑1 shows the Retrieve Context Source Registration +interaction and Table 6.13.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription +interaction +
+
+Table 6.13.3.1-1: Get Context Source Registration Subscription request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +context source registration subscription. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.13.3.2 PATCH

+

This method is associated to the operation "Update Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.3. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.2‑1 shows the Update Context Source Registration Subscription +interaction and Table 6.13.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.2-1: Update Context Source Registration Subscription +interaction +
+
+Table 6.13.3.2-1: Patch Context Source Registration Subscription request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription Fragment +
+1 +
+Subscription Fragment including id, type and any other context source +registration subscription field to be changed +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.13.3.3 DELETE

+

This method is associated to the operation "Delete Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.6. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.3‑1 shows the Delete Context Source Registration Subscription +interaction and Table 6.13.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.3-1: Delete Context Source Registration Subscription +interaction +
+
+Table 6.13.3.3-1: Delete Context Source Registration Subscription +request body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.14 Resource: +entityOperations/create

+

6.14.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity creation for the NGSI-LD API.

+

6.14.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/create +
    • +
+

6.14.3 Resource +methods

+

6.14.3.1 POST

+

This method is associated to the operation "Batch Entity Creation" +and shall exhibit the behaviour defined by clause +5.6.7. Figure +6.14.3.1‑1 shows the operation interaction and Table 6.14.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.14.3.1-1: Batch Entity Creation Interaction +
+
+Table 6.14.3.1-1: Batch Entity Creation Interaction and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of entities to be created +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+String[] +
+1 +
+201 Created +
+If all entities have been successfully created, an array of Strings +containing URIs is returned in the response. Each URI represents the +Entity ID of a created entity. There is no restriction as to the order +of the Entity IDs. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully created, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully created entities, while the second array +(errors) contains information about the error for each of the +entities that could not be created. There is no restriction as to the +order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.15 Resource: +entityOperations/upsert

+

6.15.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity creation or update for the NGSI-LD +API.

+

6.15.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/upsert +
    • +
+

6.15.3 Resource +methods

+

6.15.3.1 POST

+

This method is associated to the operation "Batch Entity Creation or +Update (Upsert)" and shall exhibit the behaviour defined by clause +5.6.8. Figure +6.15.3.1‑1 shows the operation interaction and Table 6.15.3.1‑1 +describes the request body and possible responses.

+

The options query parameter for this request can take the +following values:

+
    +
  • +"replace". Indicates that all the +existing Entity content shall be replaced (default mode); +
    • +
  • +"update". Indicates that existing Entity +content shall be updated. +
    • +
+
+ +
+
+Figure 6.15.3.1-1: Batch Entity Creation or Update Interaction +
+
+Table 6.15.3.1-1: Batch Entity Creation or Update Interaction and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of entities to be created/updated +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+String[] +
+1 +
+201 Created +
+If all entities not existing prior to this request have been +successfully created and the others have been successfully updated, an +array of String (with the URIs representing the Entity IDs of the +created entities only) is returned in the response. There is no +restriction as to the order of the Entity IDs. The merely updated +entities do not take part in the response (corresponding to 204 No +Content returned in the case of updates). +
+N/A +
+N/A +
+204 No Content +
+If all entities already existed and are successfully updated, there is +no payload body in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully created or +updated, a response body containing the result of each operation +contained in the batch is returned in a BatchOperationResult +structure. It contains two arrays. The first array (success) +contains the URIs of the successfully created or updated entities, while +the second array (errors) contains information about the error +for each of the entities that could not be created or updated. There is +no restriction as to the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.16 Resource: +entityOperations/update

+

6.16.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity update for the NGSI-LD API.

+

6.16.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/update +
    • +
+

6.16.3 Resource +methods

+

6.16.3.1 POST

+

This method is associated to the operation "Batch Entity Update" and +shall exhibit the behaviour defined by clause +5.6.9. Figure +6.16.3.1‑1 shows the operation interaction and Table 6.16.3.1‑1 +describes the request body and possible responses.

+

The options query parameter for this request can take the +following values:

+
    +
  • +"noOverwrite". Indicates that no +attribute overwrite shall be performed. +
    • +
+
+ +
+
+Figure 6.16.3.1-1: Batch Entity Update Interaction +
+
+Table 6.16.3.1-1: Batch Entity Update Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of Entities to be updated +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities have been successfully updated, there is no payload body +in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully updated, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully updated entities, while the second array +(errors) contains information about the error for each of the +entities that could not be updated. There is no restriction as to the +order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.17 Resource: +entityOperations/delete

+

6.17.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity deletion for the NGSI-LD API.

+

6.17.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/delete +
    • +
+

6.17.3 Resource +methods

+

6.17.3.1 POST

+

This method is associated to the operation "Batch Entity Delete" and +shall exhibit the behaviour defined by clause +5.6.10. Figure +6.17.3.1‑1 shows the operation interaction and Table 6.17.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.17.3.1-1: Batch Entity Delete Interaction +
+
+Table 6.17.3.1-1: Batch Entity Delete Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+String[] +
+1 +
+Array of String (URIs representing Entity IDs) to be deleted +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities existed and have been successfully deleted, there is no +payload body in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If some or all of the entities have not been successfully deleted, or +did not exist, a response body containing the result of each operation +contained in the batch is returned in a BatchOperationResult +structure. It contains two arrays. The first array (success) +contains the URIs of the successfully deleted entities, while the second +array (errors) contains information about the error for each of +the entities that could not be deleted. There is no restriction as to +the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.18 Resource: +temporal/entities/

+

6.18.1 Description

+

This resource represents the Temporal +Evolution of Entities known to an NGSI-LD +system.

+

6.18.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/ +
    • +
+

6.18.3 Resource +methods

+

6.18.3.1 POST

+

This method is associated to the operation "Create or Update Temporal +Evolution of an Entity" and shall exhibit the behaviour defined by clause +5.6.11, taking the temporal representation of Entity to be created +from the HTTP request payload body. Figure +6.18.3.1‑1 shows this interaction and Table 6.18.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity +interaction +
+
+Table 6.18.3.1-1: Post EntityTemporal request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the temporal representation of the Entity that is to be created (or +updated). +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+Upon creation success, the HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+N/A +
+N/A +
+204 No Content +
+Upon update success. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +member should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable Entity +
+It is used to indicate that the operation is not available, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.18.3.2 GET

+

This method is associated to the operation "Query Temporal Evolution +of Entities" and shall exhibit the behaviour defined by clause +5.7.4, providing the Temporal Evolution of the matching Entities as +part of the HTTP response payload body. In addition to this method, an +alternative way to perform "Query Temporal Evolution of Entities" +operations via POST is defined in clause +6.24. Figure +6.18.3.2‑1 shows this interaction.

+
+ +
+
+Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.18.3.2‑1 +and Table +6.18.3.2‑2 describes the request body and possible responses.

+
+Table 6.18.3.2-1: Temporal Evolution Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved. +
+type +
+String +
+0..1 +
+
+It shall be 1 if attrs is not present, unless the execution of +the request is limited to local scope (see clause +5.5.13). +
+Selection of Entity Types as per clause +4.17. "*" is +also allowed as a value and local is implicitly set to +true and shall not be explicitly set tofalse. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids. +
+attrs +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if type is not present, unless the execution of the +request is limited to local scope (see clause +5.5.13). +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes
+(Properties or Relationships) to be retrieved. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or an +Attribute name). +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or an +Attribute name). +
+
+When defined, the listed Entity members are removed from each Entity +within the payload. +
+q +
+String +
+0..1 +
+Query as per clause +4.9. +
+expandValues +
+Comma separated list of strings +
+0..1 +
+
+ +
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes whose values shall be expanded into URIs according to +the supplied @context prior to executing a query. It is part of +query. +
+jsonKeys +
+Comma separated list of strings +
+0..1 +
+
+ +
+Each String is an Attribute (Property or Relationship) name. +
+
+Values of the identified attributes are to be considered uninterpretable +as JSON-LD and should not be expanded against the supplied +@context using JSON-LD type coercion prior to executing the +query. +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9. +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present +
+Geometry as per clause +4.10. It is part of geoquery. +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present +
+Geo relationship as per clause +4.10. It is part of geoquery. +
+coordinates +
+String +
+0..1 +
+
+It shall be one if georel or geometry are present +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery. +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored if no geoquery is present +
+The name of the GeoProperty that contains the geospatial data +that will be used to resolve the geoquery. By default, will be +location. (See clause +4.7). +
+timeproperty +
+String +
+0..1 +
+It represents a Temporal Property name.
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8). +
+timerel +
+String +
+1 +
+It represents the temporal relationship as defined by clause +4.11.
+Allowed values: "before", "after", "between". +
+timeAt +
+String +
+1 +
+representing the timeAt parameter as defined by clause +4.11.
+It shall be a DateTime. +
+endTimeAt +
+String +
+0..1 +
+It representing the endTimeAt parameter as defined by clause +4.11.
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between". +
+lastN +
+Positive integer +
+0..1 +
+Only the last n instances, per Attribute, per Entity (under the +specified time interval) shall be retrieved. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response.
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+aggrMethods +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if aggregatedValues is present in the +options parameter +
+Each String represents an aggregation method, as defined by clause +4.5.19.
+Only applicable if "aggregatedValues" is +present in the options parameter. +
+aggrPeriodDuration +
+String +
+0..1 +
+It represents the duration of each period used for the aggregation as +defined by clause +4.5.19.
+If not specified, it defaults to a duration of 0 seconds and is +interpreted as a duration spanning the whole time-range specified by the +temporal query. +
+
+Only applicable if "aggregatedValues" is present in the +options parameter. +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19) +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+entityMap +
+Boolean +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response. +
+entityMapLifetime +
+String +
+0..1 +
+Suggested duration, represented in ISO 8601 format [17], for which the requester +wants the EntityMap to exist. The actual expiresAt time of the EntityMap +shall be set by the Context Broker or Context Source, possibly +overriding the requested duration. Only applicable if entityMap +is set to true. +
+splitEntities +
+Boolean +
+0..1 +
+If true it is assumed that single Entities are distributed +between different Context Brokers and/or Context Sources and this has to +be taken into account when applying any kind of filters (q, geoQ, +scopeQ, Attributes etc.). If false it is expected that Context +Broker and/or Context Source always have complete Entities, which allows +applying filters locally. +
+
+The parameter does not apply in case local is true. +
+
+The default value should be decided by implementation; it should be +configurable. +
+
+Table 6.18.3.2-2: Query Entities History request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal[] +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +
+A response body containing the query result as a list of temporal +representation of Entities. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that contains the resource URI of the +EntityMap resource used in the operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.19 Resource: +temporal/entities/{entityId}

+

6.19.1 Description

+

This resource is associated to the Temporal +Evolution of an Entity known to an NGSI-LD +system.

+

6.19.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.19.2‑1.

+
+Table 6.19.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the entity to be retrieved +
+

6.19.3 Resource +methods

+

6.19.3.1 GET

+

This method is associated to the operation "Retrieve Temporal +Evolution of an Entity" and shall exhibit the behaviour defined by clause +5.7.3. The Entity identifier is the value of the resource URI +variable entityId. Figure +6.19.3.1‑1 shows the retrieve temporal representation of an entity +interaction.

+
+ +
+
+Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.19.3.1‑1 +and Table +6.19.3.1‑2 describes the request body and possible responses.

+
+Table 6.19.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+attrs +
+Comma separated list of strings +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be retrieved. If not specified, all Attributes +related to the temporal representation of an Entity shall be retrieved. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or an +Attribute name). +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", +"type", "scope" or an +Attribute name). +
+
+When defined, the listed Entity members are removed from each Entity +within the payload. +
+timeproperty +
+String +
+0..1 +
+It represents a Temporal Property name.
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8). +
+timerel +
+String +
+0..1 +
+
+It shall be 1 if timeAt is present +
+It represents the Temporal Relationship as defined by clause +4.11.
+Allowed values: "before", "after", "between". +
+timeAt +
+String +
+0..1 +
+
+It shall be 1 if timerel is present +
+It represents the timeAt parameter as defined by clause +4.11.
+It shall be a DateTime. +
+endTimeAt +
+String +
+0..1 +
+
+It shall be 1 if timerel is equal to "between" +
+It represents the endTimeAt parameter as defined by clause +4.11.
+It shall be a DateTime. +
+lastN +
+Positive integer +
+0..1 +
+Only the last n Attribute instances (under the concerned time interval) +shall be retrieved. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response.
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+aggrMethods +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if aggregatedValues is present in the +options parameter +
+Each String represents the aggregation methods as defined by clause +4.5.19.
+Only applicable if "aggregatedValues" is +present in the options parameter. +
+aggrPeriodDuration +
+String +
+0..1 +
+It represents the duration of each period used for the aggregation as +defined by clause +4.5.19.
+If not specified, it defaults to a duration of 0 seconds and is +interpreted as a duration spanning the whole time-range specified by the +temporal query. +
+
+Only applicable if "aggregatedValues" is present in the +options parameter. +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+
+Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal +
+1 +
+200 OK +
+A response body containing the JSON-LD temporal representation of the +target Entity containing the selected Attributes. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.19.3.2 DELETE

+

This method is associated to the operation "Delete Temporal Evolution +of an Entity" and shall exhibit the behaviour defined by clause +5.6.16. The Entity identifier is the value of the resource URI +variable entityId. Figure +6.19.3.2‑1 shows the delete entity interaction and Table 6.19.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction +
+
+Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body +and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

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

+

6.20.1 Description

+

This resource represents all the Attributes (Properties or +Relationships) of a Temporal Evolution of an +Entity.

+

6.20.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/ +
    • +
+

Resource URI variables for this resource are defined in Table +6.20.2‑1.

+
+Table 6.20.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+

6.20.3 Resource +methods

+

6.20.3.1 POST

+

This method is bound to the "Add Attributes to Temporal Evolution of +an Entity" operation and shall exhibit the behaviour defined by clause +5.6.12. The Entity identifier is the value of the resource URI +variable entityId. The data to be added shall be contained in the +HTTP request payload body. Figure +6.20.3.1‑1 shows the Add Attributes interaction and Table 6.20.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity +interaction +
+
+Table 6.20.3.1-1: Add Attributes to Temporal Evolution of
+an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal Fragment +
+1 +
+EntityTemporal Fragment containing a complete representation of the +Attribute instances to be added. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were added successfully. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

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

+

6.21.1 Description

+

This resource represents an Attribute (Property or Relationship) of a +Temporal Evolution of an +Entity.

+

6.21.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.21.2‑1.

+
+Table 6.21.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+

6.21.3 Resource +methods

+

6.21.3.1 DELETE

+

This method is associated to the operation "Delete Attribute from +Temporal Evolution of an Entity" and shall exhibit the behaviour defined +by clause +5.6.13. The Entity identifier is the value of the resource URI +variable entityId. The Attribute name is the value of the +resource URI variable attrId. Figure +6.21.3.1‑1 shows the "Delete Attribute from Temporal Evolution of an +Entity" interaction, Table 6.21.3.1‑1 +shows the delete parameters to be supported and Table 6.21.3.1‑2 +describes the request body and possible responses.

+
+ +
+
+Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution
+of an Entity interaction +
+
+Table 6.21.3.1-1: Delete parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Cardinality +
+Remarks +
+deleteAll +
+Boolean +
+0..1 +
+If true, all attribute instances are deleted. Otherwise (default) +only the Attribute instance specified by the datasetId is +deleted. In case neither the deleteAll flag nor a datasetId is +present, the default Attribute instance is deleted. +
+datasetId +
+String +
+0..1 +
+Shall be a valid URI. Specifies the datasetId of the dataset to +be deleted. +
+
+Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of
+an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) or +Attribute name not known to the system. See clause 6.3.2. +
+

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

+

6.22.1 Description

+

This resource represents an Attribute (Property or Relationship) +instance of a Temporal Evolution of an +Entity.

+

6.22.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/{attrId}/{instanceId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.22.2‑1.

+
+Table 6.22.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+instanceId +
+Id (URI) identifying a particular Attribute instance +
+

6.22.3 Resource +methods

+

6.22.3.1 PATCH

+

This method is associated to the operation "Modify attribute instance +from Temporal Evolution of an Entity" and shall exhibit the behaviour +defined by clause +5.6.14. The Entity identifier is the value of the resource URI +variable entityId. The attribute name is the value of the +resource URI variable attrId. The instance identifier is the +value of the resource URI variable instanceId. Figure +6.22.3.1‑1 shows the Modify Attribute instance interaction and Table 6.22.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution +interaction +
+
+Table 6.22.3.1-1: Modify Attribute instance from
+Temporal Evolution request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal Fragment +
+1 +
+EntityTemporal Fragment containing a complete representation of the +Attribute instance to be replaced. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI), attribute +name or instance identifier not known to the system. See clause 6.3.2. +
+

6.22.3.2 DELETE

+

This method is associated to the operation "Delete Attribute instance +from Temporal Evolution of an Entity" and shall exhibit the behaviour +defined by clause +5.6.15. The Entity identifier is the value of the resource URI +variable entityId. The Attribute name is the value of the +resource URI variable attrId. The instance identifier is the +value of the resource URI variable instanceId. Figure +6.22.3.2‑1 shows the Delete Attribute instance interaction and Table 6.22.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of +an Entity interaction +
+
+Table 6.22.3.2-1: Delete Attribute instance from
+Temporal Evolution of an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI), attribute +name or instance identifier not known to the system. See clause 6.3.2. +
+

6.23 Resource: +entityOperations/query

+

6.23.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable querying for entities by means of a POST method. The +behaviour of this clause mirrors the one in clause 6.4.3.2, which +performs the "Query Entity" operation (defined by clause +5.7.2) by means of a GET method. The reason to provide an +alternative via POST is that, using GET:

+
    +
  1. +The client may end up assembling very long URLs, due to the URI +parameters for id, q‚ type, attrs, etc., +being included in the URL. Problems with too long URLs may arise with +some applications that cut URLs to a maximum length. +
    2. +
  2. +There is a need to URL-encode the resulting URL. By using POST, there is +no need to url-encode. +
    3. +
+

6.23.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/query +
    • +
+

6.23.3 Resource +methods

+

6.23.3.1 POST

+

This method is associated to the operation "Query Entities" and shall +exhibit the behaviour defined by clause +5.7.2. Figure +6.23.3.1‑1 shows the operation interaction and Table 6.23.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.23.3.1-1: Query Entity via POST Interaction +
+
+Table 6.23.3.1-1: Query Entity via POST Interaction and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity[] +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +

A response body +containing the query result as a list of Entities.

+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+GeoJSON FeatureCollection +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +
+If the Accept Header indicates that the Entities are to be rendered as +GeoJSON, a response body containing the query result as GeoJSON +FeatureCollection is returned. +
+
+ +
+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.24 Resource: +temporal/entityOperations/query

+

6.24.1 Description

+

A sub-resource, pertaining to the temporal/entityOperations/ +resource, intended to enable temporal querying for entities by means of +a POST method. The behaviour of this clause mirrors the one in clause 6.18.3.2, which +performs the "Query Temporal Evolution of +Entities" (defined by clause +5.7.4) operation by means of a GET method. The reason to provide an +alternative via POST is that, using GET:

+
    +
  1. +The client may end up assembling very long URLs, due to the URI +parameters for id, q‚ type, attrs, etc., +being included in the URL. Problems with too long URLs may arise with +some applications that cut URLs to a maximum length. +
    2. +
  2. +There is a need to URL-encode the resulting URL. By using POST, there is +no need to url-encode. +
    3. +
+

6.24.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entityOperations/query +
    • +
+

6.24.3 Resource +methods

+

6.24.3.1 POST

+

This method is associated to the operation "Query Temporal Evolution +of Entities" and shall exhibit the behaviour defined by clause +5.7.4. Figure +6.24.3.1‑1 shows the operation interaction and Table 6.24.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.24.3.1-1: Temporal Query Entity via POST Interaction +
+
+Table 6.24.3.1-1: Temporal Query Entity via POST Interaction request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal[] +
+1 +
+200 OK +
+
+201 Created (in case an EntityMap has been (re)created) +
+A response body containing the query result as a list of Entities. +
+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.25 Resource: types/

+

6.25.1 Description

+

This resource represents the entity types available in an NGSI-LD +system.

+

6.25.2 Resource +definition

+

Resource URI:

+
    +
  • +/types/ +
    • +
+

6.25.3 Resource +methods

+

6.25.3.1 GET

+

This method is associated to the operations "Retrieve Available +Entity Types" and "Retrieve Details of Available Entity Types" (if the +details parameter is set to true) and shall exhibit the +behaviour defined by clauses 5.7.5 +and 5.7.6 +respectively.

+
+ +
+
+Figure 6.25.3.1-1: Retrieve Available Entity Types interaction +
+

The request parameters that shall be supported are those defined in +Table +6.25.3.1‑1 and Table 6.25.3.1‑2 +describes the request body and possible responses.

+
+Table 6.25.3.1-1: Retrieve Available Entity Types: optional parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+If true, then detailed entity type information represented as an +array with elements of the Entity Type data structure (clause +5.2.25) is to be returned +
+
+Table 6.25.3.1-2: Retrieve Available Entity Types request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTypeList +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the +EntityTypeList (clause +5.2.24) is to be returned, unless details=true is specified. +
+EntityType[] +
+1 +
+200 OK +
+If details=true is specified, a response body containing a +JSON-LD array with elements of the EntityType data structure (clause +5.2.25) is to be returned. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.26 Resource: +types/{type}

+

6.26.1 Description

+

This resource represents the specified entity type for which entity +instances are available in an NGSI-LD system.

+

6.26.2 Resource +definition

+

Resource URI:

+
    +
  • +/types/{type} +
    • +
+

Resource URI variables for this resource are defined in Table +6.26.2‑1.

+
+Table 6.26.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+type +
+Name of the entity type for which detailed information is to be +retrieved. The Fully Qualified Name (FQN) as well as the short name can +be used, given that the latter is part of the JSON-LD @context +provided. +
+

6.26.3 Resource +methods

+

6.26.3.1 GET

+

This method is associated to the operation "Retrieve Available Entity +Type Information" and shall exhibit the behaviour defined by clause +5.7.7. The entity type is the value of the resource URI variable +"type". Figure +6.26.3.1‑1 shows the retrieve available entity type interaction.

+
+ +
+
+Figure 6.26.3.1-1: Retrieve Available Entity Type interaction +
+

Table +6.26.3.1‑1 describes the request body and possible responses.

+
+Table 6.26.3.1-1: Retrieve Available Entity Type request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTypeInfo +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the detailed +information about the available entity type. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an entity type not known to the +system, see clause 6.3.2. +
+

6.27 Resource: +attributes/

+

6.27.1 Description

+

This resource represents the attributes available in an NGSI-LD +system.

+

6.27.2 Resource +definition

+

Resource URI:

+
    +
  • +/attributes/ +
    • +
+

6.27.3 Resource +methods

+

6.27.3.1 GET

+

This method is associated to the operations "Retrieve Available +Attributes" and "Retrieve Details of Available Attributes" (if the +details parameter is set to true) and shall exhibit the +behaviour defined by clauses 5.7.8 +and 5.7.9 +respectively.

+
+ +
+
+Figure 6.27.3.1-1: Retrieve Available Attributes interaction +
+

The request parameters that shall be supported are those defined in +Table +6.27.3.1‑1 and Table 6.27.3.1‑2 +describes the request body and possible responses.

+
+Table 6.27.3.1-1: Retrieve Available Attributes: optional parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+If true, then detailed attribute information represented as an +array with elements of the Attribute data structure (clause +5.2.28) is to be returned +
+
+Table 6.27.3.1-2: Retrieve Available Attributes request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+AttributeList +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the +AttributeList (clause +5.2.27) is to be returned, unless details=true is specified. +
+Attribute[] +
+1 +
+200 OK +
+If details=true is specified, a response body containing a +JSON-LD array with elements of the Attribute data structure (clause +5.2.28) is to be returned. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.28 Resource: +attributes/{attrId}

+

6.28.1 Description

+

This resource represents the specified attribute that belongs to +entity instances existing within the NGSI-LD system.

+

6.28.2 Resource +definition

+

Resource URI:

+
    +
  • +/attributes/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.28.2‑1.

+
+Table 6.28.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+attrId +
+Name of the attribute for which detailed information is to be retrieved. +The Fully Qualified Name (FQN) as well as the short name can be used, +given that the latter is part of the JSON-LD @context provided. +
+

6.28.3 Resource +methods

+

6.28.3.1 GET

+

This method is associated to the operation "Retrieve Available +Attribute Information" and shall exhibit the behaviour defined by clause +5.7.10. The attribute is the value of the resource URI variable +"attrId". Figure +6.28.3.1‑1 shows the retrieve available attribute information +interaction.

+
+ +
+
+Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction +
+

Table +6.28.3.1‑1 describes the request body and possible responses.

+
+Table 6.28.3.1-1: Retrieve Available Attribute Information request body +and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Attribute +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the detailed +information about the available attribute. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an attribute name not known to the +system, see clause 6.3.2. +
+

6.29 Resource: +jsonldContexts/

+

6.29.1 Description

+

This resource represents the @contexts known to an NGSI-LD +system.

+

6.29.2 Resource +definition

+

Resource URI:

+
    +
  • +/jsonldContexts/ +
    • +
+

6.29.3 Resource +methods

+

6.29.3.1 POST

+

This method is bound to the operation "Add @context" and shall +exhibit the behaviour defined by clause +5.13.2, taking the @context to be added from the HTTP request +payload body. Figure +6.29.3.1‑1 shows the Add @context interaction and Table 6.29.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.29.3.1-1: Add @context interaction +
+
+Table 6.29.3.1-1: Add @context request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+JSON Object +
+1 +
+Payload body in the request contains a JSON object that has a root node +named @context, which represents a JSON-LD "local context". +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the local +URI of the added @context. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.29.3.2 GET

+

This method is associated to the operation "List @contexts" +and shall exhibit the behaviour defined by clause +5.13.3, and it provides information about stored @contexts as +part of the HTTP response payload body. Figure +6.29.3.2‑1 shows the List @contexts interaction.

+
+ +
+
+Figure 6.29.3.2-1: List @contexts interaction +
+

The request parameters that shall be supported by implementations are +those defined in Table 6.29.3.2‑1 +and Table +6.29.3.2‑2 describes the request body and possible responses.

+
+Table 6.29.3.2-1: List @contexts request parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+Whether a list of URLs or a more detailed list of JSON Objects is +requested +
+kind +
+String +
+0..1 +
+Can be either "Cached", "Hosted", or "ImplicitlyCreated" +
+
+Table 6.29.3.2-2: List @contexts request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+String[] +
+
+or +
+
+JSON Object[] +
+1 +
+200 OK +
+A response body containing a list of URLs or a list of JSON Objects, as +defined in clause +5.13.3.5, representing metadata about stored @contexts. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.30 Resource: +jsonldContexts/{contextId}

+

6.30.1 Description

+

This resource represents a JSON-LD @context stored in the +broker's internal @context storage.

+

6.30.2 Resource +definition

+

Resource URI:

+
    +
  • +/jsonldContexts/{contextId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.30.2‑1.

+
+Table 6.30.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+contextId +
+Local identifier of the @context to be managed (served or +deleted). For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. +
+

6.30.3 Resource +methods

+

6.30.3.1 GET

+

This method is associated to the operation "Serve @context" +and shall exhibit the behaviour defined by clause +5.13.4. The @context identifier is the value of the resource +URI variable "contextId". Figure +6.30.3.1‑1 shows the HTTP Serve @context interaction.

+
+ +
+
+Figure 6.30.3.1-1: Serve @context interaction +
+

The request parameters that shall be supported by implementations are +those defined in Table 6.30.3.1‑1 +and Table +6.30.3.1‑2 describes the request body and possible responses.

+
+Table 6.30.3.1-1: Serve @contexts request parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+Whether the content of the @context or its metadata is requested +
+
+Table 6.30.3.1-2: Serve @context request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+JSON Object +
+1 +
+200 OK +
+If the parameter details is false or missing, response body +contains a JSON object that has a root node named @context, which +represents a JSON-LD "local context". +
+
+If the parameter details is true, response body contains a JSON +object as defined in clause +5.13.4.5, which metadata of a JSON-LD "local context". +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable +
+It is used when a client indicated an @context of type "Cached", see clause 6.3.2. +
+

6.30.3.2 DELETE

+

This method is associated to the operation "Delete and Reload +@context" and shall exhibit the behaviour defined by clause +5.13.5. The Entity identifier is the value of the resource URI +variable "contextId". Figure +6.30.3.2‑1 shows the delete entity interaction. The request +parameters that shall be supported are those defined in Table 6.30.3.2‑1 +and Table +6.30.3.2‑2 describes the request body and possible responses.

+
+Table 6.30.3.2-1: Delete and Reload @context request parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+reload +
+Boolean +
+0..1 +
+indicates to perform a download and replace of the @context, as +specified in clause +5.13.5.4. +
+
+ +
+
+Figure 6.30.3.2-1: Delete and Reload @context interaction +
+
+Table 6.30.3.2-2: Delete and Reload @context request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+504 Gateway Timeout +
+It is used when re-downloading fails. +
+

6.31 Resource: +entityOperations/merge

+

6.31.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity merge for the NGSI-LD API.

+

6.31.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/merge +
    • +
+

6.31.3 Resource +methods

+

6.31.3.1 POST

+

This method is associated to the operation "Batch Entity Merge" and +shall exhibit the behaviour defined by clause +5.6.20. Figure +6.31.3.1‑1 shows the operation interaction and Table 6.31.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.31.3.1-1: Batch Entity Merge Interaction +
+
+Table 6.31.3.1-1: Batch Entity Merge Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of Entities to be merged. +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities have been successfully merged, there is no payload body +in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully merged, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully merged entities, while the second array +(errors) contains information about the error for each of the +entities that could not be merged-patched. There is no restriction as to +the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.32 Resource: +entityMaps/{entityMapId}

+

6.32.1 Description

+

This resource represents an EntityMap available in the broker's +internal storage or memory.

+

6.32.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityMaps/{entityMapId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.32.2‑1.

+
+Table 6.32.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityMapId +
+Id (URI) of the EntityMap to be retrieved, updated or deleted. +
+

6.32.3 Resource +methods

+

6.32.3.1 GET

+

This method is associated to the operation "Retrieve EntityMap" and +shall exhibit the behaviour defined by clause +5.14.1. The EntityMap identifier is the value of the resource URI +variable "entityMapId". Figure +6.32.3.1‑1 shows the Retrieve EntityMap interaction and Table 6.32.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.3.1-1: Retrieve EntityMap +
+
+Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityMap +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +entity. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an EntityMap identifier not known to +the system, see clause 6.3.2. +
+

6.32.3.2 PATCH

+

This method is associated to the operation "Update EntityMap" and +shall exhibit the behaviour defined by clause +5.14.2. The EntityMap identifier is the value of the resource URI +variable "entityMapId". Figure +6.32.3.2‑1 shows the Update EntityMap interaction and Table 6.32.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.3.2-1: Update EntityMap +
+
+Table 6.32.3.2-1: Update EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityMap Fragment +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the EntityMap fragment with which the EntityMap is to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an EntityMap identifier not known to +the system, see clause 6.3.2. +
+
+ +
+

6.32.3.3 DELETE

+

This method is associated to the operation "Delete EntityMap" and +shall exhibit the behaviour defined by clause +5.14.3. The Entity identifier is the value of the resource URI +variable "contextId". Figure +6.32.3.3‑1 shows the delete entity interaction and Table 6.32.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.3.3-1: Delete and Reload @context interaction +
+
+Table 6.32.3.3-1: Delete EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+

6.33 Resource: +info/sourceIdentity

+

6.33.1 Description

+

This resource represents identity information about the Context Source itself.

+

6.33.2 Resource +definition

+

Resource URI:

+
    +
  • +/info/sourceIdentity +
    • +
+

6.33.3 Resource +methods

+

6.33.3.1 GET

+

This method is associated to the operation "Retrieve Context Source +Identity Information" and shall exhibit the behaviour defined by clause +5.15.1. Figure +6.33.3.1‑1 shows the Retrieve Context Source Identity Information +interaction and Table 6.33.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.33.3.1-1: Retrieve Context Source Identity Information +
+
+Table 6.33.3.1-1: Retrieve Context Source Identity Information request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+ContextSourceIdentity +
+1 +
+200 No Content +
+A response body containing the JSON-LD representation of the Context +Source Identity Information. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Context Sources to +indicate that retrieval of the Context Source information is unsupported +see . +
+

6.34 Resource: +entityMaps

+

6.34.1 Description

+

This resource represents the Entity maps in an NGSI-LD system.

+

6.34.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityMaps/ +
    • +
+

6.34.3 Resource +methods

+
+6.34.3.1 GET +
+

This method is associated to the operation "Create EntityMap for +Query Entities" and shall exhibit the behaviour defined by clause +5.14.4, providing an EntityMap as part of the HTTP response payload +body. In addition to this method, an alternative way to perform "Create +EntityMap for Query Entities " operations via POST is defined in clause 6.34.3.2. Figure 6.34.3.1‑1 shows the Create +EntityMap for Query Entities interaction.

+
+ +
+
+Figure 6.34.3.1‑1: +Create EntityMap for Query Entities +interaction +
+

The query parameters that shall be supported by implementations are +the same as those for Query Entities and can be found in Table 6.4.3.2‑1. +Table 6.34.3.1‑1 describes the request +body and possible responses.

+
+ +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+ +
+
+ +
+
+Table 6.34.3.1‑1: +Create EntityMap for Query Entities request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
N/AN/A
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
EntityMap1201 Created

A response body containing the +entityMap with the identifiers of the Entities matching the query.

+

The HTTP response shall include an "NGSILD-EntityMap" HTTP header +that contains the resource URI of the EntityMap resource created in the +operation.

EntityMap1203 Non-Authoritative Information
+As above, but returning an altered response +body, amended to conform to a specific version of the NGSI-LD +specification as mandated in clause +4.3.6.8. +
+
+ +
+
+The response shall also include a "Preference-Applied" HTTP header set +to "ngsi-ld=<conformant-version>". +
ProblemDetails (see IETF RFC 7807 +[10])1400 Bad Request

It is used to indicate that the +request or its content is incorrect, see clause +6.3.2.

+

In the returned ProblemDetails structure, the detail +attribute should convey more information about the error.

ProblemDetails (see IETF RFC 7807 +[10])1501 Not ImplementedIt is used by Registered Context Sources +to indicate that the data format of the request is unsupported see clause +6.3.7.
+
+ +
+

6.34.3.2 POST

+

This method is associated to the operation "Create EntityMap for +Query Entities" and shall exhibit the behaviour defined by clause +5.14.4. Figure +6.34.3.2‑1 shows the operation interaction and Table 6.34.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.34.3.2-1: Create EntityMap for Query Entities via POST +Interaction +
+
+Table 6.34.3.2-1: Create EntityMap for Query Entities via POST +Interaction request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityMap +
+1 +
+201 Created +
+A response body containing the entityMap with the identifiers of the +Entities matching the query. +
+
+ +
+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.35 Resource: +temporal/entityMaps

+

6.35.1 Description

+

This resource is used for creating entityMaps based on temporal +queries in an NGSI-LD system.

+

6.35.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entityMaps/ +
    • +
+

6.35.3 Resource +methods

+

6.35.3.1 GET

+

This method is associated to the operation "Create EntityMap for +Query Temporal Evolution of Entities" and shall exhibit the behaviour +defined by clause +5.14.5, an EntityMap as part of the HTTP response payload body. In +addition to this method, an alternative way to perform "Create EntityMap +for Query Temporal Evolution of Entities" operations via POST is defined +in clause 6.35.3.2. Figure +6.35.3.1‑1 shows this interaction.

+
+ +
+
+Figure 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of +Entities interaction +
+

The query parameters that shall be supported by implementations are +the same as those for Query Temporal Evolution of Entities and can be +found in Table +6.18.3.2‑1. Table 6.35.3.1‑1 +describes the request body and possible responses.

+
+ +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+
+ +
+
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+Table 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of +Entities request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityMap +
+1 +
+201 Created +
+A response body containing the entityMap with the identifiers of the +Entities matching the query. +
+
+ +
+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.35.3.2 POST

+

This method is associated to the operation "Create EntityMap for +Query Temporal Evolution of Entities" and shall exhibit the behaviour +defined by clause +5.14.5. Figure +6.35.3.2‑1 shows the operation interaction and Table 6.35.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of +Entities via POST Interaction +
+
+Table 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of +Entities via POST Interaction request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityMap +
+1 +
+201 Created +
+A response body containing the entityMap with the identifiers of the +Entities matching the query. +
+
+ +
+
+The HTTP response shall include an "NGSILD-EntityMap" HTTP header that +contains the resource URI of the EntityMap resource created in the +operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ + diff --git a/public/11-tabapi-operation-definition.html b/public/11-tabapi-operation-definition.html new file mode 100644 index 0000000000000000000000000000000000000000..c11e22f641a8e162de7a27477643bc598525428d --- /dev/null +++ b/public/11-tabapi-operation-definition.html @@ -0,0 +1,20678 @@ + + + + + + + 5 API Operation Definition + + + + + + + +
+

5 API Operation +Definition

+

5.1 Introduction

+

This clause defines data structures and operations of the NGSI-LD +API. No specific binding is assumed. Clause 6 maps +these operations and data types to the HTTP REST binding.

+
+NOTE: In UML diagrams dotted arrows denote a response to a request. +
+

5.2 Data Types

+

5.2.1 Introduction

+

Implementations shall support the data types defined by the clauses +below. For each member defined by each data type (including nested ones) +a term shall be added to the Core @context, as mandated by clause +4.5.

+

None of the members described admit a null value directly, as +when a JSON-LD processor encounters null, the associated entry or +value is always removed when expanding the JSON-LD document.

+

However, in the context of a partial update or merge operation (see +clauses 5.5.8 +and 5.5.12), +an NGSI-LD Null shall be used to indicate the removal of a target +member. Thus, for representing deleted elements in notifications and in +the temporal evolution, 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 LanguageProperty, respectively. In all +other cases, implementations shall raise an error of type +BadRequestData if an NGSI-LD Null value is encountered.

+

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

+

Non-normative JSON Schema [i.11] definitions of the +referred data types are also available at [i.13].

+

The use of URI in the context of the present document also includes +the use of International Resource Identifiers (IRIs) as defined in IETF +RFC 3987 [23], which +extends the use of characters to Unicode characters [22] beyond the ASCII +character set, enabling the support of languages other than English.

+

5.2.2 Common members

+

The JSON-LD representation of NGSI-LD Entity, Property, Relationship, +Context Source Registration and +Subscription can include the common members described by Table +5.2.2‑1.

+

Those members are read-only, and shall be automatically generated by +NGSI-LD implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+

In query or retrieve operations implementations shall only generate +common members (Table +5.2.2‑1) when the Context +Consumer explicitly asks for their inclusion. Clause +6.3.11 defines the mechanism offered by the HTTP binding for such +purpose.

+
+Table 5.2.2-1: Common members of NGSI-LD elements +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+createdAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity creation timestamp. See clause +4.8 +
+modifiedAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity last modification timestamp. See clause +4.8 +
+deletedAt +
+string +
+DateTime (clause +4.6.3) +
+0..1 +
+Entity deletion timestamp. See clause +4.8
+It is only used in notifications reporting deletions and in the temporal +representation of Entities (clause +4.5.6), Properties (clause +4.5.7), Relationships (clause +4.5.8) and LanguageProperties (clause +5.2.32) and VocabProperties (clause +5.2.35) and JsonProperties (clause +5.2.38) +
+

5.2.3 @context

+

When encoding NGSI-LD Entities, Context +Source Registrations, Subscriptions and Notifications, as pure +JSON-LD (MIME type "application/ld+json"), a user @context +(as described in clause +4.4) shall be included as a special member of the corresponding +JSON-LD Object. Table +5.2.3‑1 gives a precise definition of this special member.

+
+Table 5.2.3-1: JSON-LD @context tagged member +
+ +++++++ + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. +
+

5.2.4 Entity

+

This type represents the data needed to define an NGSI-LD Entity as +mandated by clause +4.5.1.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.4‑1.

+
+Table 5.2.4-1: NGSI-LD Entity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Entity ID +
+type +
+String or String[] +
+ +
+1 +
+Entity Type(s). Both short hand string(s) (type name) or URI(s) are +allowed +
+ +
+scope +
+String or String[] +
+See clause +4.18 +
+0..1 +
+Scope +
+location +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+Default geospatial Property of an entity. See clause +4.7 +
+observationSpace +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+See clause +4.7 +
+operationSpace +
+GeoProperty +
+See datatype definition in clause +5.2.7 +
+0..1 +
+See clause +4.7 +
+<Property name> +
+
+ +
+Property +
+
+or Property[]1 +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Property as mandated by clause +4.5.2. +
+GeoProperty or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperty as mandated by clause +4.5.2. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperty as mandated by clause +4.5.18. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperty as mandated by clause +4.5.24. +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperty as mandated by clause +4.5.20. +
+ListProperty or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperty as mandated by clause +4.5.21. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationship as mandated by clause +4.5.3. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationship as mandated by clause +4.5.22. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

5.2.5 Property

+

This type represents the data needed to define a Property as +mandated by clause +4.5.2.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.5‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type member can be omitted as type="Property" can be inferred from the +presence of the value member. Furthermore, in the concise +representation of a Property, the value member cannot be a +GeoJSON Object (as defined in clause +4.7) as it would be interpreted as a GeoProperty (see clause +5.2.7).

+
+Table 5.2.5-1: NGSI-LD Property data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Property" +
+1 +
+Node type +
+value +
+Any JSON value as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Property Value +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+unitCode +
+String +
+As mandated by [15] +
+0..1 +
+Property Value's unit code +
+<Property name> +
+Property or
+Property[]1 +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the Property +
+GeoProperty or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the Property. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the Property. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the Property +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the Property. +
+ListProperty or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the Property. +
+<Relationship name> +
+Relationship or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the Property. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the Property +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

The following output only members (defined by Table +5.2.5-2) of the Property data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.5-2: Output only members of the NGSI-LD Property data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of Properties +
+0..1 +
+URI uniquely identifying a Property instance as mandated by clause +4.5.7 +
+
+ +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousValue +
+Any JSON value as defined by IETF RFC 8259 [6] +
+Only used in Notifications, if the +showChanges option is explicitly requested +
+0..1 +
+Previous Property Value +
+

5.2.6 Relationship

+

This type represents the data needed to define a Relationship +as mandated by clause +4.5.3.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.6‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type +member can be omitted as type="Relationship" can be inferred from the +presence of the object member.

+
+Table 5.2.6-1: NGSI-LD Relationship data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Relationship" +
+1 +
+Node type +
+object +
+String or String[] +
+Valid URI or an Array of Valid URIs +
+1 +
+Relationship's target object +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of target relationship objects +
+objectType +
+String or String[] +
+ +
+0..1 +
+Node Type of the Relationship's target object. Both short hand string(s) +(type name) or URI(s) are allowed +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property or
+Property[]1 +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the Relationship +
+GeoProperty or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the Relationship. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the +Relationship +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the Relationship +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the Relationship. +
+ListProperty or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the Relationship. +
+<Relationship name> +
+Relationship or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the Relationship. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the +Relationship. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

The following output only members (defined by Table +5.2.6-2) of the Relationship data structure are also defined. +They are read-only and shall be generated by NGSI-LD implementations. +They shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.6-2: Output only members of the NGSI-LD Relationship data type +
+ ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+entity +
+Entity or Entity[]1 +
+See datatype definition in clause 5.2.4. +
+
+ +
+
+Only used in Linked Entity Retrieval, if the join=inline option +is explicitly requested +
+0..1 +
+An inline Entity obtained by Linked Entity Retrieval, corresponding to +the Relationship's target object See clause +4.5.23.2 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of Relationships +
+0..1 +
+URI uniquely identifying a Relationship instance as mandated by clause +4.5.8 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousObject +
+String +
+Valid URI. Only used in Notifications, if the showChanges option +is explicitly requested +
+0..1 +
+Previous Relationship's target object +
+NOTE 1: one-to-N Relationships expand to an array of Entity +elements, since there can be more than one target object URI specified. +
+
+ +
+

5.2.7 GeoProperty

+

This type represents the data needed to define a +GeoProperty.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.7‑1 below. The datatype definition defines all the required +attributes for the normalized representation. In the concise +representation, the Attribute type member can be omitted as "GeoProperty" can be inferred from the presence +of the value member holding a GeoJSON Geometry as mandated +by clause +4.7.

+
+Table 5.2.7-1: NGSI-LD GeoProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "GeoProperty" +
+1 +
+Node type +
+value +
+JSON Object +
+As mandated by clause +4.7 +
+1 +
+Geolocation encoded as GeoJSON [8] +
+ +
+ +
+ +
+ +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property
+or Property[]1 +
See datatype definition in clause +5.2.50..NProperties of the GeoProperty
+GeoProperty or GeoProperty[]1 +
See datatype definition in clause +5.2.70..NGeoPropertiesof the GeoProperty.
LanguageProperty or +LanguageProperty[]1See datatype definition in clause +5.2.320..NLanguagePropertiesof the GeoProperty.
JsonProperty or +JsonProperty[]1See datatype +definition in clause +5.2.380..NJsonPropertiesof the GeoProperty
VocabPropertyor VocabProperty[]1See datatype definition in clause +5.2.350..NVocabPropertiesof the GeoProperty.
+ListProperty +
+

or +ListProperty[]1

See datatype definition in clause +5.2.360..NListPropertiesof the GeoProperty.
+<Relationship name> +
+
+ +
+Relationship or Relationship[]2 +
See datatype definition in clause +5.2.60..NRelationships of the GeoProperty
ListRelationshipor ListRelationship[]2See datatype definition in clause +5.2.370..NListRelationshipsof the GeoProperty.
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

The following output only members (defined by Table +5.2.8-2) of the GeoProperty data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.7-2: Output only members of the NGSI-LD GeoProperty data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of GeoProperties +
+0..1 +
+URI uniquely identifying a GeoProperty instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousValue +
+Any JSON value as defined by IETF RFC 8259 [6] +
+Only used in Notifications, if the +showChanges option is explicitly requested +
+0..1 +
+Previous GeoProperty Value +
+

5.2.8 EntityInfo

+

This type represents what Entities, Entity Types or group of Entity +IDs (as a regular expression pattern mandated by IEEE 1003.2™ [11]) can be provided (by +Context Sources).

+

The JSON members shall follow the indications provided in Table +5.2.8‑1. id takes precedence over idPattern.

+

Notice that Cardinality of type being 1 implies that it is not +possible to register what Entities can be provided by a Context Source just by their id or +idPattern (i.e. without specifying their type).

+
+Table 5.2.8-1: EntityInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+0..1 +
+Entity identifier +
+idPattern +
+String +
+Regular expression as per IEEE 1003.2™ [11] +
+0..1 +
+A regular expression which denotes a pattern that shall be matched by +the provided or subscribed Entities +
+type +
+String or String[] +
+Fully Qualified Name of an Entity Type or the Entity Type name as a +short-hand string. See clause +4.6.2 +
+1 +
+Entity Type (or JSON array, in case of Entities with multiple Entity +Types) +
+

5.2.9 CSourceRegistration

+

This type represents the data needed to register a new Context Source.

+

The supported JSON members shall follow the indications provided in +Table +5.2.9‑1.

+
+Table 5.2.9-1: CSourceRegistration data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI. +
+
+Unique registration identifier. (JSON-LD @id). +
+0..1 +
+At creation time, if it is not provided, it will be assigned during +registration process and returned to client. +
+
+It cannot be later modified in update operations. +
+type +
+String +
+It shall be equal to "ContextSourceRegistration" +
+1 +
+JSON-LD @type +
+
+Use reserved type for identifying Context Source Registration +
+registrationName +
+String +
+Non-empty string +
+0..1 +
+A name given to this Context Source +Registration +
+contextSourceAlias +
+String +
+Non-empty string. Pseudonym field as defined in IETF RFC 7230 [27] +
+0..1 +
+A previously retrieved unique id for a registered Context Source which is used to identify +loops. +
+
+ +
+
+In the multi-tenancy use case (see clause +4.14), this id shall be used to identify a specific Tenant within a registered Context Source. +
+description +
+String +
+Non-empty string +
+0..1 +
+A description of this Context Source +Registration +
+information +
+RegistrationInfo[] +
+See data type definition in clause +5.2.10. Empty array (0 length) is not allowed +
+1 +
+Describes the Entities, Properties and Relationships for which the Context Source may be able to provide +information +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of Attributes that the Context Source can provide, defined as per +clause +4.5.5. +
+tenant +
+String +
+ +
+0..1 +
+Identifies the Tenant that has to be +specified in all requests to the Context +Source that are related to the information registered in this +Context Source Registration. If not +present, the default Tenant is +assumed. Should only be present in systems supporting multi-tenancy +
+observationInterval +
+TimeInterval +
+See data type definition in clause +5.2.11 +
+0..1 +
+If present, the Context Source can be +queried for Temporal Entity Representations. (If latest Entity +information is also provided, a separate Context Registration is needed +for this purpose). The observationInterval specifies the time +interval for which the Context Source +can provide Entity information as specified by the observedAt +Temporal Property. A temporal query based on the observedAt +Temporal Property, which is the default, is matched against the +observationInterval for overlap +
+managementInterval +
+TimeInterval +
+See data type definition in clause +5.2.11 +
+0..1 +
+If present, the Context Source can be +queried for Temporal Entity Representations. (If latest Entity +information is also provided, a separate Context Registration is needed +for this purpose). The managementInterval specifies the time +interval for which the Context Source +can provide Entity information as specified by the createdAt, +modifiedAt and deletedAt Temporal Properties. A temporal +query based on the createdAt, modifiedAt or +deletedAt Temporal Property is matched against the +managementInterval for overlap +
+location +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Location for which the Context +Source may be able to provide information +
+observationSpace +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Geographic location that includes the observation spaces of all entities +as specified by their respective observationSpace +GeoProperty for which the Context +Source may be able to provide information +
+operationSpace +
+GeoJSON Geometry as mandated by clause +4.7 +
+ +
+0..1 +
+Geographic location that includes the operation spaces of all entities +as specified by their respective operationSpace +GeoProperty for which the Context +Source may be able to provide information +
+expiresAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Provides an expiration date. When passed the Context Source Registration will become +invalid and the Context Source might +no longer be available +
+endpoint +
+String +
+It shall be a dereferenceable URI +
+1 +
+Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD +interface +
+contextSourceInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to convey optional information to provide +when contacting the registered Context +Source +
+scope +
+String or +
+
+String[] +
+Scope(s) +
+0..1 +
+Scopes (see clause +4.18) for which the Context +Source has Entities +
+mode +
+String +
+It shall be one of: +
+
+"inclusive", "exclusive", "redirect" or "auxiliary" +
+
+ +
+
+The mode is assumed to be "inclusive" if +not explicitly defined +
+0..1 +
+The definition of the mode of distributed operation (see clause +4.3.6) supported by the registered Context Source +
+operations +
+String[] +
+Entries are limited to the named API operations and named operation +groups (see clause +4.20) +
+0..1 +
+The definition limited subset of API operations supported by the +registered Context Source +
+
+ +
+
+If undefined, the default set of operations is "federationOps" (see clause +4.20) +
+refreshRate +
+String +
+String representing a duration in ISO 8601 format [17] +
+0..1 +
+An indication of the likely period of time to elapse between updates at +this registered endpoint. +
+
+ +
+
+Brokers may optionally use this information to help implement caching. +
+management +
+Registration +
+
+Management +
+
+Info +
+See data type definition in clause +5.2.34 +
+0..1 +
+Holds additional optional registration management information that can +be used to limit unnecessary distributed operation requests. +
+<CSource Property name> +
+Any JSON value as defined by IETF RFC 8259 [6] +
+ +
+0..N +
+Each Context Source Property pertains +to a characteristic of the Context +Source the Context Source +Registration describes +
+

The members (defined by Table 5.2.9-2) of the +CSourceRegistration data structure are also defined. They are +read-only and shall be automatically generated by NGSI-LD +implementations. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.9-2: Additional members of the CSourceRegistration data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+status +
+String +
+Allowed values: +
+

"ok"

+

"failed"

+0..1 +
+Read-only., Status of the Registration. It shall be "ok" if the last attempt to perform a +distributed operation succeeded. It shall be "failed" if the last attempt to perform a +distributed operation failed +
+timesSent +
+Number +
+0 or greater value +
+0..1 +
+Number of times that the +registration triggered a distributed operation, including failed +attempts. +
+timesFailed +
+Number +
+0 or greater value +
+0..1 +
+Number of times that the +registration triggered a distributed operation request that +failed. +
+lastSuccess +
+String +
+DateTime(clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the +instant when the last successfully distributed operation was sent. +Created on first successful operation. +
lastFailure
+String +
+DateTime(clause +4.6.3) +
+0..1 +
Timestamp +corresponding to the instant when the last distributed operation +resulting in a failure (for +instance, in the +HTTPbinding, an HTTPresponse code other than 2xx) +was returned.
+

5.2.10 RegistrationInfo

+

The supported JSON members shall follow the requirements provided in +Table +5.2.10‑1.

+
+Table 5.2.10-1: RegistrationInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entities +
+EntityInfo[] +
+See data type definition in clause +5.2.8. Empty array (0 length) is not allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the entities for which the CSource may be able to provide +information +
+propertyNames +
+String[] +
+Property names as short hand strings or URIs. Empty array is not +allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the Properties that the CSource may be able to provide +
+relationshipNames +
+String[] +
+Relationship names as short hand strings or URIs. Empty array is not +allowed. Restrictions in clause +4.3.6 apply as well +
+0..1 +
+Describes the Relationships that the CSource may be able to provide +
+

At least one element of RegistrationInfo shall be present.

+

5.2.11 TimeInterval

+

The supported JSON members shall follow the requirements provided in +Table +5.2.11‑1.

+
+Table 5.2.11-1: TimeInterval data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+startAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Describes the start of the time interval +
+endAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Describes the end of the time interval. If not present the interval is +open +
+

5.2.12 Subscription

+

This datatype represents a Context Subscription.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.12‑1.

+
+Table 5.2.12-1: Subscription data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+0..1 +
+Subscription identifier (JSON-LD @id). At creation time, if it is +not provided, it will be assigned during subscription process and +returned to client. +
+
+It cannot be later modified in update operations +
+type +
+String +
+It shall be equal to "Subscription" +
+1 +
+JSON-LD @type +
+subscriptionName +
+String +
+ +
+0..1 +
+A (short) name given to this Subscription +
+description +
+String +
+ +
+0..1 +
+Subscription description +
+entities +
+EntitySelector[] +
+See data type definition in clause +5.2.33. Empty array (0 length) is not allowed. +
+
+ +
+
+Mandatory if timeInterval is present, unless the execution of the +request is limited to local scope (see clause +5.5.13) +
+0..1 +
+Entities subscribed +
+watchedAttributes +
+String[] +
+Attribute name as short hand strings or URIs. Empty array (0 length) is +not allowed. +
+
+ +
+
+if timeInterval is present it shall not appear (0 cardinality). +
+0..1 +
+Watched Attributes (Properties or Relationships). If not defined it +means any Attribute +
+localOnly +
+Boolean +
+ +
+0..1 +
+If localOnly=true then the subscription only pertains to the +Entities stored locally. +
+notificationTrigger +
+String[] +
+Valid notification triggers are "entityCreated", +"entityUpdated", +"entityDeleted", +"attributeCreated", +"attributeUpdated", +"attributeDeleted" +
+0..1 +
+The notification triggers listed indicate what kind of changes shall +trigger a notification. If not present, the default is the combination +"attributeCreated" and "attributeUpdated". "entityUpdated" +is equivalent to the combination "attributeCreated", "attributeUpdated" and "attributeDeleted" +
+timeInterval +
+Number +
+Greater than 0 +
+
+if watchedAttributes is present it shall not appear (0 +cardinality) +
+0..1 +
+Indicates that a notification shall be delivered periodically regardless +of attribute changes. Actually, when the time interval (in seconds) +specified in this value field is reached +
+q +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Query that shall be met by subscribed entities in order to trigger the +notification +
+geoQ +
+GeoQuery +
+See data type definition in clause 5.2.13 +
+0..1 +
+Geoquery that shall be met by subscribed entities in order to trigger +the notification +
+csf +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Context source filter that shall be met by Context Source Registrations describing +Context Sources to be used for Entity +Subscriptions +
+isActive +
+Boolean +
+true by default +
+0..1 +
+Allows clients to temporarily pause the subscription by making it +inactive. true indicates that the Subscription is under +operation. false indicates that the subscription is paused, and +notifications shall not be delivered +
+notification +
+NotificationParams +
+See data type definition in clause +5.2.14 +
+1 +
+Notification details +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+0..1 +
+Expiration date for the subscription +
+throttling +
+Number +
+Greater than 0. Fractional values are allowed. If timeInterval is +present it shall not appear (0 cardinality) +
+0..1 +
+Minimal period of time in seconds which shall elapse between two +consecutive notifications +
+temporalQ +
+TemporalQuery +
+See data type definition in clause +5.2.21 +
+0..1 +
+Temporal Query to be used only in +Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal +information +
+scopeQ +
+String +
+See clause +4.19 +
+0..1 +
+Scope query +
+lang +
+String +
+A natural language filter in the form of a IETF RFC 5646 [28] language code +
+0..1 +
+Language filter to be applied to the query (clause +4.15) +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of the Attribute instances to be selected for +each matched Attribute as per clause +4.5.5. +
+jsonldContext +
+String +
+Dereferenceable URI +
+ +
+The dereferenceable URI of the JSON-LD @context to be used when +sending a notification resulting from the subscription. If not provided, +the @context used for the subscription shall be used as a +default. +
+

At least one of (a) entities or (b) watchedAttributes +shall be present, unless the member localOnly +is set to true, in which case the execution of the request +is limited to local scope (see clause +5.5.13).

+

The members (defined by Table 5.2.12-2) of the Subscription +data structure are also defined. They are read-only and shall be +automatically generated by NGSI-LD implementations. They shall not be +provided by Context Subscribers. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore +them.

+
+Table 5.2.12-2: Additional members of the Subscription data type +
+ +++++++ + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+status +
+String +
+Allowed values: +
+

"active"

+

"paused"

+

"expired"

+0..1 +
+Read-only. Provided by the system when querying the details of a +subscription +
+

5.2.13 GeoQuery

+

This datatype represents a geoquery used for Subscriptions.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.13‑1.

+
+Table 5.2.13-1: GeoQuery data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+geometry +
+String +
+A valid GeoJSON [8] +geometry type excepting GeometryCollection +
+1 +
+
+ +
+Type of the reference geometry +
+coordinates +
+JSON Array or String +
+A JSON Array coherent with the geometry type as per IETF RFC 7946 +[8] +
+1 +
+Coordinates of the reference geometry. For the sake of JSON-LD +compatibility It can be encoded as a string as described in clause +4.7.1 +
+georel +
+String +
+A valid geo-relationship as defined by clause +4.10 +
+1 +
+Geo-relationship ("near", "within", etc.) +
+geoproperty +
+String +
+Attribute name as short hand string or URI +
+0..1 +
+Specifies the GeoProperty to which the GeoQuery is to be applied. If not +present, the default GeoProperty is location +
+

5.2.14 NotificationParams

+

5.2.14.1 NotificationParams +data type definition

+

This datatype represents the parameters that allow to convey the +details of a notification.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.14.1‑1.

+
+Table 5.2.14.1-1: NotificationParams data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+attributes +
+String[] +
+Attribute name as short hand strings or URIs. Empty array (0 length) is +not allowed +
+0..1 +
+A synonym for a combination of the pick andq parameter. +Deprecated +
+
+ +
+
+Attribute names to be included in the notification payload body. If +undefined it will mean all Attributes +
+sysAttrs +
+Boolean +
+false by default +
+0..1 +
+If true, the system generated attributes createdAt and +modifiedAt are included in the response payload body, in the case +of a deletion also deletedAt +
+format +
+String +
+It shall be one of: "normalized", "concise", "simplified" (or its synonym +"keyValues") +
+0..1 +
+Conveys the representation format of the entities delivered at +notification time. By default, it will be in the normalized format +
+pick +
+String[] +
+Entity member ("id", "type", "scope” or a projected Attribute name as a valid +attribute projection language string as per clause +4.21). Empty array (0 length) is not allowed +
+0..1 +
+When defined, every Entity within the payload body is reduced down to +only contain the specified Entity members. +
+omit +
+String[] +
+Entity member ("id", "type", "scope" or a projected Attribute name) as a valid +attribute projection language string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, the specified Entity members are removed from each Entity +within the payload +
+showChanges +
+Boolean +
+false by default +
+0..1 +
+If true the previous value (previousValue) of +Properties or languageMap (previousLanguageMap) of +Language Properties or object (previousObject) of +Relationships is provided in addition to the current one. This requires +that it exists, i.e. in case of modifications and deletions, but not in +the case of creations. +
+
+showChanges cannot be true in case format is "keyValues" +
+join +
+String +
+It shall be one of: "flat", "inline", "@none" +
+0..1 +
+String representing the type of Linked +Entity retrieval to apply. +
+
+By default, it will be "@none" +
+joinLevel +
+Number +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. Default is 1. Only applicable if join parameter is "flat", or "inline", +
+endpoint +
+Endpoint +
+See data type definition in clause 5.2.15 +
+1 +
+Notification endpoint details +
+

5.2.14.2 Output +only members

+

The following output only members (defined by Table +5.2.14.2-1) of the NotificationParams data structure are also +defined. They are read-only and shall be automatically generated by +NGSI-LD implementations. They shall not be provided by +Context Subscribers. In the event that they are provided (in +update or create operations) NGSI-LD implementations shall ignore +them.

+

In query or retrieve operations involving Subscriptions, +implementations shall generate them as part of their representation.

+
+Table 5.2.14.2-1: Output only members of the NotificationParams data +structure +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+timesSent +
+Number +
+Greater than 0 +
+0..1 +
+Number of times that the notification has been sent. Provided by the +system when querying the details of a subscription +
+timesFailed +
+Number +
+Greater than 0 +
+0..1 +
+Number of times an unsuccessful response (or timeout) has been received +when delivering the notification. Provided by the system when querying +the details of a subscription +
+lastNotification +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last notification has +been sent. Provided by the system when querying the details of a +subscription +
+lastFailure +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last notification +resulting in failure (for instance, in the HTTP binding, an HTTP +response code different than 200) has been sent. Provided by the system +when querying the details of a subscription +
+lastSuccess +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp corresponding to the instant when the last successful (200 OK +response) notification has been sent. Provided by the system when +querying the details of a subscription +
+status +
+String +
+Allowed values: +
+
+"ok", "failed" +
+0..1 +
+Status of the Notification. It shall be "ok" if the last attempt to notify the +subscriber succeeded. It shall be "failed" if the last attempt to notify the +subscriber failed +
+

5.2.15 Endpoint

+

This datatype represents the parameters that are required in order to +define an endpoint for notifications. This can include, in addition the +endpoint's URI, a generic{key, value} array, named receiverInfo, +which contains, in a generalized form, whatever extra information the +Context Broker shall convey to the +receiver in order for the Context +Broker to successfully communicate with receiver (e.g. +Authorization material), or for the receiver to correctly interpret the +received content (e.g. the Link URL to fetch an @context). +Additionally, it can include another generic{key, value} array, named +notifierInfo, which contains the configuration that the Context Broker needs to know in order to +correctly set up the communication channel towards the receiver (e.g. +MQTT-Version, MQTT-QoS, in case of MQTT binding, as defined in clause +7.2).

+

The supported JSON members shall follow the indications provided in +Table +5.2.15‑1.

+
+Table 5.2.15-1: Endpoint data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+uri +
+String +
+Dereferenceable URI +
+1 +
+URI which conveys the endpoint which will receive the notification. +
+accept +
+String +
+MIME type. It shall be one of: +
+

"application/json"

+

"application/ld+json"

+

"application/geo+json"

+0..1 +
+Intended to convey the MIME type of the notification payload body (JSON, +or JSON-LD, or GeoJSON). If not present, default is "application/json". +
+timeout +
+Number +
+Greater than 0 +
+0..1 +
+Maximum period of time in +milliseconds which may elapse before a notification is assumed to have +failed. The NGSI-LDsystem can override this value. This +only applies if the binding protocol always returns a response. +
+cooldown +
+Number +
+Greater than 0 +
+0..1 +
Once a failure has +occurred, minimum period of time in milliseconds which shall elapse +before attempting to make a subsequent notification to the same endpoint +after failure.
+
+If requests are +received before the cooldown period has expired, no notification is +sent.
+receiverInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to convey optional information to the +receiver. +
+notifierInfo +
+KeyValuePair[] +
+ +
+0..1 +
+Generic {key, value} array to set up the communication channel. +
+

5.2.16 BatchOperationResult

+

This datatype represents the result of a batch operation.

+

The supported JSON members shall follow the indications provided in +Table +5.2.16‑1.

+
+Table 5.2.16-1: BatchOperationResult data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+success +
+String[] +
+Array of valid URIs +
+1 +
+Array of Entity IDs corresponding to the Entities that were successfully +treated by the concerned operation. Empty Array if no Entity was +successfully treated +
+errors +
+BatchEntityError[] +
+ +
+1 +
+One array item per Entity in error. Empty Array if no errors happened +
+

5.2.17 BatchEntityError

+

This datatype represents an error raised (associated to a particular +Entity) during the execution of a batch or distributed operation.

+

The supported JSON members shall follow the indications provided in +Table +5.2.17‑1.

+
+Table 5.2.17-1: BatchEntityError data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entityId +
+String +
+Valid URI +
+1 +
+Entity ID corresponding to the Entity in error +
+registrationId +
+String +
+Valid URI +
+0..1 +
+Registration Id corresponding to a failed distributed operation +(optional) +
+error +
+ProblemDetails (see IETF RFC 7807 [10]) +
+ +
+1 +
+One instance per Entity in error +
+

5.2.18 UpdateResult

+

This datatype represents the result of Attribute update (append or +update) operations in the NGSI-LD API regardless of whether local or +distributed.

+

The supported JSON members shall follow the indications provided in +Table +5.2.18‑1.

+
+Table 5.2.18-1: UpdateResult data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+updated +
+String[] +
+ +
+1 +
+List of Attributes (represented by their name) that were appended or +updated. +
+notUpdated +
+NotUpdatedDetails[] +
+See clause +5.2.19 +
+1 +
+List which contains the Attributes (represented by their name) that were +not updated, together with the reason for not being updated. +
+

5.2.19 NotUpdatedDetails

+

This datatype represents additional information provided by an +implementation when an Attribute update did not happen. See also clause +5.2.18.

+

The supported JSON members shall follow the indications provided in +Table +5.2.19‑1.

+
+Table 5.2.19-1: NotUpdatedDetails data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+attributeName +
+String +
+ +
+1 +
+Attribute name +
+reason +
+String +
+ +
+1 +
+Reason for not having changed such Attribute +
+registrationId +
+String +
+Valid URI +
+0..1 +
+Registration Id corresponding to a failed distributed operation +(optional) +
+

5.2.20 EntityTemporal

+

This datatype represents the Temporal +Evolution of an Entity.

+

This is the same datatype as mandated by clause 5.2.4 +with the only deviation that the representation of Properties and +Relationships shall be the temporal one (arrays of (Property or +Relationship) instances represented by JSON-LD objects) as +defined in clauses 4.5.7 +and 4.5.8. +Alternatively it is possible to specify the EntityTemporal by using the +"Simplified temporal representation of an Entity", as defined in clause +4.5.9.

+

5.2.21 TemporalQuery

+

This datatype represents a temporal query.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.21‑1.

+
+Table 5.2.21-1: TemporalQuery data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+timerel +
+String +
+Allowed values: "before", "after" and "between" +
+1 +
+Represents the temporal relationship as defined by clause +4.11 +
+timeAt +
+String representing the timeAt parameter as defined by clause +4.11 +
+It shall be a DateTime +
+1 +
+ +
+endTimeAt +
+String representing the endTimeAt parameter as defined by clause +4.11 +
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between" +
+0..1 +
+ +
+timeproperty +
+String representing a Temporal Property name +
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8) +
+0..1 +
+ +
+

5.2.22 KeyValuePair

+

This datatype represents the optional information that is required +when contacting an endpoint for notifications.

+

The supported members shall follow the indications provided in Table +5.2.22‑1. They are intended to represent a key/value pair.

+

Example optional information includes additional HTTP Headers such +as:

+
    +
  • +The HTTP Authentication Header. +
    • +
  • +The HTTP Prefer Header (IETF RFC 7240 [26]) used when notifying the +GeoJSON Endpoint. +
    • +
+
+Table 5.2.22-1: KeyValuePair data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+key +
+String +
+Binding-dependent +
+1 +
+The key of the key/value pair +
+value +
+String +
+Binding-dependent +
+1 +
+The value of the key/value pair +
+

5.2.23 Query

+

This datatype represents the information that is required in order to +convey a query when a "Query Entities" operation or a "Query Temporal +Evolution of Entities" operation is to be performed (as per clauses 5.7.2 +and 5.7.4, +respectively).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.23‑1.

+
+Table 5.2.23-1: Query data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "Query" +
+1 +
+JSON-LD @type +
+entities +
+EntitySelector[] +
+See data type definition in clause +5.2.33. Empty array (0 length) is not allowed +
+0..1 +
+Entity IDs, id pattern and Entity types that shall be matched by +Entities in order to be retrieved +
+attrs +
+String[] +
+Attribute name as short hand strings or URIs. +
+
+Empty array (0 length) is not allowed +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+List of Attributes that shall be matched by Entities in order to be +retrieved. If not present all Attributes will be retrieved +
+pick +
+String[] +
+Entity member ("id", "type", "scope” or a projected Attribute name) as a +valid attribute projection language string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, every Entity within the payload body is reduced down to +only contain the specified Entity members. +
+omit +
+String[] +
+Entity member (“id”, “type”, "scope" or a +projected Attribute name) as a valid attribute projection language +string as per clause +4.21. Empty array (0 length) is not allowed +
+0..1 +
+When defined, the specified Entity members are removed from each Entity +within the payload +
+q +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Query that shall be matched by Entities in order to be retrieved +
+geoQ +
+GeoQuery +
+See data type definition in clause 5.2.13 +
+0..1 +
+Geoquery that shall be matched by Entities in order be retrieved +
+csf +
+String +
+A valid query string as per clause +4.9 +
+0..1 +
+Context source filter that shall be matched by Context Source Registrations describing +Context Sources to be used for +retrieving Entities +
+temporalQ +
+TemporalQuery +
+See data type definition in clause +5.2.21 +
+0..1 +
+Temporal Query to be present only for "Query Temporal Evolution of Entities" operation +(clause +5.7.4) +
+scopeQ +
+String +
+See clause +4.19 +
+0..1 +
+Scope query +
+lang +
+String +
+A natural language filter in the form of a IETF RFC 5646 [28] language code +
+0..1 +
+Language filter to be applied to the query (clause +4.15) +
+containedBy +
+String[] +
+Comma separated list of URIs. Empty array (0 length) is not allowed +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. +
+
+ +
+
+Only applicable if joinLevel is present. +
+
+ +
+
+Only applicable for the "Query Entities" operation (clause +5.7.2). +
+datasetId +
+String[] +
+Valid URIs,"@none" +for including the default Attribute instances. +
+0..1 +
+Specifies the datasetIds of the Attribute instances to be selected for +each matched Attribute as per clause +4.5.5. +
+entityMap +
+Boolean +
+ +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response. +
+
+ +
+
+Only applicable for the "Query Entities" operation (clause +5.7.2). +
+

5.2.24 EntityTypeList

+

This type represents the data needed to define the entity type list +representation as mandated by clause +4.5.10.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.24‑1.

+
+Table 5.2.24-1: NGSI-LD EntityTypeList data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+URI that is unique within the system scope. Identifier for the entity +type list +
+type +
+String +
+It shall be equal to "EntityTypeList" +
+1 +
+JSON-LD @type +
+typeList +
+String[] +
+ +
+1 +
+List containing the entity type names +
+

5.2.25 EntityType

+

This type represents the data needed to define the elements of the +detailed entity type list representation as mandated by clause +4.5.11.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.25‑1.

+
+Table 5.2.25-1: NGSI-LD EntityType data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Fully Qualified Name (FQN) of the entity type being described +
+type +
+String +
+It shall be equal to "EntityType" +
+1 +
+JSON-LD @type +
+typeName +
+String +
+ +
+1 +
+Name of the entity type, short name if contained in @context +
+attributeNamenames +
+String[] +
+ +
+1 +
+List containing the names of attributes that instances of the entity +type can have +
+

5.2.26 EntityTypeInfo

+

This type represents the data needed to define the detailed entity +type information representation as mandated by clause +4.5.12.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.26‑1.

+
+Table 5.2.26-1: NGSI-LD EntityTypeInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Fully Qualified Name (FQN) of the entity type being described +
+type +
+String +
+It shall be equal to "EntityTypeInfo" +
+1 +
+JSON-LD @type +
+typeName +
+String +
+ +
+1 +
+Name of the entity type, short name if contained in @context +
+entityCount +
+Number +
+Unsigned integer +
+1 +
+Number of entity instances of this entity type +
+attributeDetails +
+Attribute[] +
+See data type definition in clause +5.2.28. Attribute with only the elements "id", "type", +"attributeName" and "attributeTypes" +
+1 +
+List of attributes that entity instances with the specified entity type +can have +
+

5.2.27 AttributeList

+

This type represents the data needed to define the attribute list +representation as mandated by clause +4.5.13.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.27‑1.

+
+Table 5.2.27-1: NGSI-LD AttributeList data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+URI that is unique within the system scope. Identifier for the attribute +list +
+type +
+String +
+It shall be equal to "AttributeList" +
+1 +
+JSON-LD @type +
+attributeList +
+String[] +
+ +
+1 +
+List containing the attribute names +
+

5.2.28 Attribute

+

This type represents the data needed to define the attribute +information needed as:

+
    +
  • +part of the entity type information representation as mandated by clause +4.5.12; +
    • +
  • +the detailed attribute list representation as mandated by clause +4.5.14; +
    • +
  • +the attribute information representation as mandated by clause +4.5.15. +
    • +
+

The supported JSON members shall follow the requirements provided in +Table +5.2.28‑1.

+
+Table 5.2.28-1: NGSI-LD Attribute data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Full URI of attribute name +
+type +
+String +
+It shall be equal to "Attribute" +
+1 +
+JSON-LD @type +
+attributeName +
+String +
+ +
+1 +
+Name of the attribute, short name if contained in @context +
+attributeCount +
+Number +
+Unsigned integer +
+0..1 +
+Number of attribute instances with this attribute name +
+attributeTypes +
+String[] +
+ +
+0..1 +
+List of attribute types (e.g. Property, Relationship, +GeoProperty) for which entity instances exist, which contain an +attribute with this name +
+typeNames +
+String[] +
+ +
+0..1 +
+List of entity type names for which entity instances exist containing +attributes that have the respective name +
+

5.2.29 Feature

+

This data type represents a spatially bounded Entity in GeoJSON +format, as mandated by IETF RFC 7946 [8]. The supported JSON members +shall follow the requirements provided in Table +5.2.29‑1.

+
+Table 5.2.29-1: Feature data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Entity ID +
+type +
+String +
+It shall be equal to "Feature" +
+1 +
+GeoJSON Type +
+geometry +
+GeoJSON Object +
+The value field from the matching GeoProperty (as specified in clause +4.5.16) or null +
+1 +
+null if no matching GeoProperty +
+properties +
+FeatureProperties +
+See data type definition +
+1 +
+List of attributes as mandated by clause +5.2.31 +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. This field is only present if requested in the +payload by the HTTP Prefer Header (IETF RFC 7240 [26]) +
+

5.2.30 FeatureCollection

+

This data type represents a list of spatially bounded Entities in +GeoJSON format, as mandated by IETF RFC 7946 [8]. The supported JSON members +shall follow the requirements provided in Table +5.2.30‑1.

+
+Table 5.2.30-1: FeatureCollection data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "FeatureCollection" +
+1 +
+GeoJSON Type +
+features +
+Feature[] +
+See data type definition +
+1..N +
+In the case that no matches are found, features will be an empty +array +
+@context +
+URI, JSON Object, or JSON Array +
+See [2], section 5.1. +
+0..1 +
+JSON-LD @context. This field is only present if requested in the +payload by the HTTP Prefer Header (IETF RFC 7240 [26]) +
+

5.2.31 FeatureProperties

+

This data type represents the type and the associated attributes +(Properties and Relationships) of an Entity in GeoJSON +format.

+
+Table 5.2.31-1: NGSI-LD Entity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String or String[] +
+Entity Type +
+1 +
+Entity Type (or JSON array, in case of Entities with multiple Entity +Types). Both short hand string (type name) or URI are allowed. +
+<Property name> +
+
+ +
+Property or Property[]1 +
+See data type definition in clause 5.2.5 +
+0..N +
+Property as mandated by clause +4.5.2. +
+GeoProperty or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperty as mandated by clause +4.5.2. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperty as mandated by clause +4.5.18. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties as mandated by clause +4.5.24 +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperty as mandated by clause +4.5.20. +
+ListProperty or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperty as mandated by clause +4.5.21 +
+<Relationship name> +
+
+ +
+Relationship or Relationship[]2 +
+See data type definition in clause +5.2.6 +
+0..N +
+Relationship as mandated by clause +4.5.3. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationship as mandated by clause +4.5.22. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

5.2.32 LanguageProperty

+

This type represents the data needed to define a +LanguageProperty as mandated by clause +4.5.18. Note that in case of concise representation, the type +can be omitted (see clause +4.5.18.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.32‑1.

+
+Table 5.2.32-1: NGSI-LD LanguageProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+string +
+It shall be equal to "LanguageProperty" +
+1 +
+Node type +
+languageMap +
+JSON object +
+A set of key-value pairs whose keys shall be strings representing IETF +RFC 5646 [28] +language codes and whose values shall be JSON strings or arrays of JSON +strings +
+1 +
+String Property Values defined in multiple natural languages +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+
+ +
+Property or Property[]1 +
+See datatype definition in clauses 5.2.5 +
+0..N +
+Properties of the LanguageProperty. +
+GeoProperty +
+
+or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the LanguageProperty +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the LanguageProperty +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the LanguageProperty +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the LanguageProperty +
+ListProperty +
+
+or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the LanguageProperty. +
+<Relationship name> +
+Relationship +
+
+or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the LanguageProperty. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the LanguageProperty +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

The following output only members (defined by Table +5.2.32-2) of the LanguageProperty data structure are also +defined. They are read-only and shall be generated by NGSI-LD +implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+
+Table 5.2.32-2: Output only members of the NGSI-LD LanguageProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of LanguageProperties +
+0..1 +
+URI uniquely identifying a LanguageProperty instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousLanguageMap +
+JSON object +
+A set of key-value pairs whose keys shall be strings representing IETF +RFC 5646 [28] +language codes and whose values shall be JSON strings. +
+
+Only used in Notifications, if the showChanges option is +explicitly requested +
+0..1 +
+Previous Language Property's languageMap +
+

5.2.33 EntitySelector

+

This type selects which entity or group of entities are queried or +subscribed to by Context Consumers. +Entities can be specified by their id, Entity Types or group of Entity +IDs (as a regular expression pattern mandated by IEEE POSIX 1003.2™ +[11]).

+

The JSON members shall follow the indications provided in Table +5.2.33‑1. id takes precedence over idPattern.

+
+Table 5.2.33-1: EntitySelector data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+0..1 +
+Entity identifier +
+idPattern +
+String +
+Regular expression as per IEEE POSIX 1003.2™ [11] +
+0..1 +
+A regular expression which denotes a pattern that shall be matched by +the provided or subscribed Entities +
+type +
+String +
+A valid type selection string as per clause +4.17. To indicate a request for all Entities (with implied local +scope), “*” is +also allowed as a value. +
+1 +
+Selector of Entity Type(s);
+If type is specified as “*”, +implying local scope, local scope shall not be explicitly set to be +false (clause +5.5.13) for the execution of the corresponding operation. +
+

5.2.34 RegistrationManagementInfo

+

This type represents the data to alter the default behaviour of a +Context Broker when making a +distributed operation request to a registered Context Source. The supported JSON members +shall follow the indications provided in Table +5.2.34‑1. Brokers may override these recommendations.

+
+Table 5.2.34-1: RegistrationManagementInfo data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+localOnly +
+Boolean +
+ +
+0..1 +
+If localOnly=true then distributed operations associated to this +Context Source Registration will act +only on data held directly by the registered Context +
+
+Source itself (see clause +4.3.6.4). +
+cacheDuration +
+String +
+String representing a duration in ISO 8601 format [17] +
+0..1 +

Minimal period of +time which shall elapse between two consecutive context information +consumption operations (as defined in clause 5.7) related to the same context +data will occur.

+

If the +cacheDurationlatency period has not been +reached, a cached value for the entity or its attributes shall be +returned where available.

+timeout +
+Number +
+Greater than 0 +
+0..1 +
+Maximum period of time in milliseconds which may elapse before a +forwarded request is assumed to have failed. +
+cooldown +
+Number +
+Greater than 0 +
+0..1 +

Minimum period of +time in milliseconds which shall elapse before attempting to make a +subsequent forwarded request to the same endpoint after +failure.

+

If requests are +received before the cooldown period has expired, a timeout error +response for the registration is automatically returned.

+

5.2.35 VocabProperty

+

This type represents the data needed to define a VocabProperty as mandated by clause +4.5.20. In case of concise representation, the type can be +omitted (see clause +4.5.20.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.35‑1.

+
+Table 5.2.35-1: NGSI-LD VocabularyProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "VocabProperty" +
+1 +
+Node type +
+vocab +
+String or string[] +
+ +
+1 +
+String Values which shall be type coerced to URIs based on the supplied +@context +
+ +
+datasetId +
+
+ +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property +
+
+or Property[]1 +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Properties of the VocabProperty +
+GeoProperty +
+
+or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the VocabProperty. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the VocabProperty. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the VocabProperty +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the VocabProperty. +
+ListProperty +
+
+or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the VocabProperty. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the VocabProperty. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the VocabProperty. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+
+ +
+

The following output only members (defined by Table +5.2.35-2) of the VocabProperty data +structure are also defined. They are read-only and shall be generated by +NGSI-LD implementations. They shall not be provided by +Context Producers. In the event that they are provided (in update +or create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.35-2: Output only members of the NGSI-LD VocabProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of VocabProperties +
+0..1 +
+URI uniquely identifying a VocabProperty instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousVocab +
+String or String[] +
+Only used in Notifications +
+0..1 +
+Previous VocabProperty's vocab +
+
+ +
+
+ +
+

5.2.36 ListProperty

+

This type represents the data needed to define a ListProperty +as mandated by clause +4.5.21. Please note that in case of concise representation, the +type can be omitted (see clause +4.5.21.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.36‑1.

+
+Table 5.2.36-1: NGSI-LD ListProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to"ListProperty" +
+1 +
+Node type +
+valueList +
+An array of JSON values as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Ordered array of Property Values +
+ +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property list values +
+<Property name> +
+
+ +
+Property +
+
+or Property[]1 +
+See datatype definition in clauses 5.2.5 +
+0..N +
+Properties of the ListProperty. +
+GeoProperty +
+
+or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the ListProperty. +
+LanguageProperty +
+
+or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the ListProperty. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the ListProperty +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the ListProperty +
+ListProperty +
+
+or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the ListProperty. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the ListProperty. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the ListProperty. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+
+ +
+

The following output only members (defined by Table +5.2.36-2) of the ListProperty data structure are also defined. +They are read-only and shall be generated by NGSI-LD implementations. +They shall not be provided by Context +Producers. In the event that they are provided (in update or +create operations) NGSI-LD implementations shall ignore them.

+
+Table 5.2.36-2: Additional members of the NGSI-LD ListProperty data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of ListProperties +
+0..1 +
+URI uniquely identifying a ListProperty instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousValueList +
+An array of JSON values as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1 +
+Ordered array of previous Property Values +
+
+ +
+

5.2.37 ListRelationship

+

This type represents the data needed to define a +ListRelationship as mandated by clause +4.5.22. Please note that in case of concise representation, the +type can be omitted (see clause +4.5.22.3) and the objectList may also be represented as an +ordered array of Strings.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.36‑1.

+
+Table 5.2.36-1: NGSI-LD ListRelationship data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "ListRelationship" +
+1 +
+Node type +
+objectList +
+JSON Object[] or +
+
+String[] +
+
+ +

In the normalized form, each +array element holds a JSON object containing a single Attribute with a +key called "object"and where the value is a valid +URI.

+
+In the concise form, each string in the array holds a valid URI +
+1 +
+Ordered array of Relationship target objects. +
+
+ +
+
+ +
+
+ +
+ +
+datasetId +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of relationship list objects +
+objectType +
+String or String [] +
+ +
+0..1 +
+Node Type of the Relationship's target object. +
+
+Both short hand string(s) (type name) or URI(s) are allowed +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property or Property[]1 +
+See datatype definition in clause 5.2.5 +
+0..N +
+Properties of the ListRelationship. +
+GeoProperty +
+
+or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the ListRelationship. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the ListRelationship. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the ListProperty +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the ListRelationship. +
+ListProperty +
+
+or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the ListRelationship. +
+<Relationship name> +
+
+ +
+Relationship or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the ListRelationship. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the ListRelationship +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+

The following output only members (defined by Table +5.2.37-2) of the ListRelationship data structure are also +defined. They are read-only and shall be generated by NGSI-LD +implementations. They shall not be provided by Context Producers. In the event that they +are provided (in update or create operations) NGSI-LD implementations +shall ignore them.

+
+Table 5.2.36-2: Additional members of the NGSI-LD ListRelationship data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+entityList +
+Entity[] +
+See datatype definition in clause 5.2.4 +
+
+ +
+
+Only used in Linked Entity Retrieval, +if the join=inline option is explicitly requested +
+0..1 +
+An array of inline Entities obtained by Linked Entity retrieval, corresponding to +the ListRelationship's target objects See clause +4.5.23.2 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of +ListRelationships +
+0..1 +
+URI uniquely identifying a ListRelationship instance as mandated +by clause +4.5.8 +
+modifiedAt +
+String +
DateTime (clause +4.6.3)
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousObjectList +
+JSON Object[] or +
+
+String[] +
+
+ +

In the normalized form, each +array element holds a JSON object containing a containing a single +Attribute with a key called "object"and +where the value is a valid URI.

+
+In the concise form, each string in the array holds a valid URI +
+0..1 +
+Ordered array of previous Relationship target objects +
+
+ +
+

5.2.38 JsonProperty

+

This type represents the data needed to define a JsonProperty as +mandated by clause +4.5.24. In case of concise representation, the type can be +omitted (see clause +4.5.24.3).

+

The supported JSON members shall follow the requirements provided in +Table +5.2.38‑1.

+
+Table 5.2.38-1: NGSI-LD JsonProperty data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "JsonProperty" +
+1 +
+Node type +
+json +
+JSON +
+ +
+1 +
+Raw unexpandable JSON which shall not be interpreted as JSON-LD using +the supplied @context +
+ +
+datasetId +
+
+ +
+String +
+Valid URI +
+0..1 +
+It allows identifying a set or group of property values +
+observedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+Timestamp. See clause +4.8 +
+<Property name> +
+Property +
+
+or Property[]1 +
+See datatype definitions in clauses 5.2.5 +
+0..N +
+Properties of the JsonProperty +
+GeoProperty +
+
+or GeoProperty[]1 +
+See datatype definition in clause +5.2.7 +
+0..N +
+GeoProperties of the JsonProperty. +
+LanguageProperty or LanguageProperty[]1 +
+See datatype definition in clause +5.2.32 +
+0..N +
+LanguageProperties of the JsonProperty. +
+JsonProperty or JsonProperty[]1 +
+See datatype definition in clause +5.2.38 +
+0..N +
+JsonProperties of the JsonProperty. +
+VocabProperty or VocabProperty[]1 +
+See datatype definition in clause +5.2.35 +
+0..N +
+VocabProperties of the JSONPropertry. +
+ListProperty +
+
+or ListProperty[]1 +
+See datatype definition in clause +5.2.36 +
+0..N +
+ListProperties of the JsonProperty. +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[]2 +
+See datatype definition in clause +5.2.6 +
+0..N +
+Relationships of the JsonProperty. +
+ListRelationship or ListRelationship[]2 +
+See datatype definition in clause +5.2.37 +
+0..N +
+ListRelationships of the JsonProperty. +
+NOTE 1: For each Property (or subclass of Property) +identified by the same Property name, there can be one or more instances +separated by datasetId. +
+
+NOTE 2: For each Relationship (or subclass of Relationship) +identified by the same Relationship name, there can be one or more +instances separated by datasetId. +
+
+ +
+

The following outp ut only members (defined by Table +5.2.38-2) of the JsonProperty data structure are also defined. They are +read-only and shall be generated by NGSI-LD implementations. They shall +not be provided by Context Producers. In the event that they are +provided (in update or create operations) NGSI-LD implementations shall +ignore them.

+
+Table 5.2.38-2: Output only members of the NGSI-LD JsonProperty data +type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+createdAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated creation timestamp. See clause +4.8 +
+deletedAt +
+String +
+DateTime (clause +4.6.3) +
+
+It is only used in notifications reporting deletions +
+0..1 +
+System generated deletion timestamp. See clause +4.8 +
+instanceId +
+String +
+Valid URI. Only used in temporal representation of JsonProperties +
+0..1 +
+URI uniquely identifying a JsonProperty instance as mandated by clause +4.5.7 +
+modifiedAt +
+String +
+DateTime (clause +4.6.3) +
+0..1 +
+System generated last modification timestamp. See clause +4.8 +
+previousJson +
+JSON +
+Only used in Notifications +
+0..1 +
+Previous JsonProperty's json +
+
+ +
+

5.2.39 EntityMap

+

This type represents the data needed to define an EntityMap as +mandated by clause +4.5.25.

+

The supported JSON members shall follow the requirements provided in +Table +5.2.39‑1.

+
+Table 5.2.39-1: NGSI-LD EntityMap data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+type +
+String +
+It shall be equal to "EntityMap" +
+1 +
+Node type +
+expiresAt +
+String +
+DateTime (see clause +4.6.3) +
+1 +
+Expiration date for the EntityMap +
+

The following output only members (defined by Table +5.2.39-2) of the EntityMap data structure are also defined. They +are read-only and shall be generated by NGSI-LD implementations. They +shall not be provided by Context +Producers. In the event that they are provided in update +operations NGSI-LD implementations shall ignore them.

+
+Table 5.2.39-2: Additional members of the NGSI-LD EntityMap data type +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+entityMap +
+JSON +
+A set of key-value pairs whose keys shall be strings representing Entity +ids and whose values shall be an array holding every CSourceRegistration +id which is relevant to the ongoing Context Information Consumption +request (see clause +4.21). +
+
+ +
+
+The key "@none" shall be +used to refer to an Entity that is held locally +
+1 +
+System generated mapping of Entities to CSourceRegistrations. +
+
+ +
+
+ +
+linkedMaps +
+JSON +
+A set of key-value pairs whose keys shall be strings representing +CSourceRegistration ids which are relevant to the ongoing Context +Information request and whose values shall represent the associated +EntityMap id used by the ContextSource +
+1 +
+System generated mapping of Context CSourceRegistrations to a URI +indicating which EntityMaps was used by the Context Source +
+
+ +
+

5.2.40 Context +Source Identity

+

This type represents the data uniquely identifying a Context Source, and if the Context Source supports multi-tenancy (see +clause +4.14) uniquely identifying a Tenant within that Context Source.

+

The supported JSON members shall follow the requirements provided in +table +5.2.40‑1.

+
+Table 5.2.40-1: Context Source Identity data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restriction +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Context Source ID +
+type +
+String +
+It shall be equal to "ContextSourceIdentity” +
+1 +
+Node type +
+ +
+contextSourceExtras +
+JSON +
+ +
+0..1 +
+Instance specific information relevant to the configuration of +the Context Source itself in +raw unexpandable JSON which shall not be interpreted as JSON-LD using +the supplied @context +
+contextSourceUptime +
+String +
+String representing a duration in ISO 8601 format [17] +
+1 +
+Total Duration that the Context +Source has been available +
+contextSourceTimeAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Current time observed at the Context +Source. Timestamp See clause +4.8 +
+contextSourceAlias +
+String +
+Non-empty string. Pseudonym field as defined in IETF RFC 7230 +[27] +
+1 +
+A unique id for a Context +Source which can be used to identify loops. +
+
+ +
+
+In the multi-tenancy use case (see clause +4.14), this id shall be identify a specific Tenant within a registered Context Source. +
+
+ +
+

5.3 Notification +data types

+

5.3.1 Notification

+

This datatype represents the parameters that allow building a +notification to be sent to a subscriber. How to build this notification +is detailed in clause +5.8.6.

+

The supported JSON members shall follow the indications provided in +Table +5.3.1‑1.

+
+Table 5.3.1-1: Notification data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+Notification identifier (JSON-LD @id). It shall be automatically +generated by the implementation +
+type +
+String +
+It shall be equal to "Notification" +
+1 +
+JSON-LD @type +
+subscriptionId +
+String +
+Valid URI +
+1 +
+Identifier of the subscription that originated the notification +
+notifiedAt +
+String +
+DateTime (clause +4.6.3) +
+1 +
+Timestamp corresponding to the instant when the notification was +generated by the system +
+data +
+NGSI-LD Entity[] or FeatureCollection +
+ +
+1 +
+The content of the notification as NGSI-LD Entities.
+See clause +5.2.4. +
+
+ +
+
+If the notification has been triggered from a Subscription that has the +notification. +
+
+endpoint.accept field set to application/geo+json then data is returned as a +FeatureCollection. In this case, if the +notification.endpoint.receiverInfo contains the key "Prefer" and it is set to the value "body=json", then the FeatureCollection +will not contain an @context field. +
+
+ +
+
+If endpoint.accept is not set or holds another value then +Entity[] is returned. +
+

5.3.2 CSourceNotification

+

This datatype represents the parameters that allow building a Context Source Notification to be sent to a +subscriber. How to build this notification is detailed in clause +5.11.7.

+

The supported JSON members shall follow the indications provided in +Table +5.3.2‑1.

+
+Table 5.3.2-1: CSourceNotification data type definition +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Restrictions +
+Cardinality +
+Description +
+id +
+String +
+Valid URI +
+1 +
+CSource notification identifier (JSON-LD @id) +
+type +
+String +
+It shall be equal to "ContextSourceNotification" +
+1 +
+JSON-LD @type +
+subscriptionId +
+String +
+Valid URI +
+1 +
+Identifier of the subscription that originated the notification +
+notifiedAt +
+String +
+DateTime (see clause +4.6.3) +
+1 +
+Timestamp corresponding to the instant when the notification was +generated by the system +
+data +
+CSource +
+
+Registration[] +
+ +
+1 +
+The content of the notification as NGSI-LD CSourceRegistrations. See clause +5.2.9 +
+triggerReason +
+String +
+TriggerReasonEnumeration (see clause +5.3.3) +
+1 +
+Indicates whether the CSources in the CSourceRegistration(s) in data are +newly matching (initial notification or creation), have been updated +(but still match) or do not match any longer +
+

5.3.3 TriggerReasonEnumeration

+

The enumeration can take one of the following values:

+
    +
  • +"newlyMatching" - describes the case that the notified +Context Source Registration(s) newly +match(es) the identified subscription. This value is used in the first +notification and whenever a new Context +Source Registration matching the Subscription has been +registered, or an existing Context Source +Registration that did not match before has been updated in such a +way that it matches now. +
    • +
  • +"updated" - describes the case that the notified Context Source Registration that was part +of a previous notification has been updated, but still matches the +Subscription. +
    • +
  • +"noLongerMatching" - describes the case that the +notified Context Source Registration +that was part of a previous notification no longer matches the +Subscription, i.e. as a result of an update or because it was deleted. +
    • +
+

5.4 NGSI-LD +Fragments

+

When updating NGSI-LD elements (Entities, Attributes, Context Source Registrations or +Subscriptions) it is necessary to have a means of describing a set of +modifications to their content.

+

An NGSI-LD Fragment is a JSON Merge Patch document [16] and [i.10] which describes +changes to be made to a target JSON-LD document using a syntax that +closely mimics the document being modified.

+

An NGSI-LD Fragment is a JSON-LD Object which shall include the +following members:

+
    +
  • +id (optional for certain bindings where it can be determined from +the operation signature). It shall be equal to the id of the target +(mutated) NGSI-LD element. Attribute Fragments do not contain explicit +ids. +
    • +
  • +type (optional for certain bindings where it can be determined +from the operation signature). It shall contain the Type name(s) of the +target NGSI-LD element. +
    • +
  • +A member (following the same data representation and nesting structure) +for each new member to be added to the target NGSI-LD element. +
    • +
  • +A member (following the same data representation and nesting structure) +for each new member to be modified in the target NGSI-LD element, which +value shall correspond to the new member value to be given. +
    • +
+
+EXAMPLE 1: The following Subscription Fragment allows the modification of +a Subscription by changing its endpoint's URI: +
+
+
+{ +
+
+ "id": "urn:ngsi-ld:Subscription:MySubscription", +
+
+"type": "Subscription", +
+
+"endpoint": { +
+
+ "uri": "http://example.org/newNotificationEndPoint" +
+
+} +
+
+} +
+
+ +
+
+
    +
  • +A member (following the same data representation and nesting structure) +with value equal to an NGSI-LD Null shall cause for the member to be +removed from the target NGSI-LD element. +
    +
    + +
    • +
+
+EXAMPLE 2: The following NGSI-LD Fragment allows the modification of an +Entity by changing its batteryLevel Attribute, updating the +observedAt sub-Attribute, removing the providedBy +sub-Attribute and removing the uncharged Attribute from the +Entity: +
+
+
+{ +
+
+"id": "urn:ngsi-ld:TemperatureSensor:001", +
+
+"type": "TemperatureSensor", +
+
+"batteryLevel": { +
+
+"type": "Property", +
+
+"value": 7, +
+
+"observedAt": "2022-03-14T12:51:02.000Z", +
+
+"providedBy": "urn:ngsi-ld:null" +
+
+}, +
+
+"uncharged" : { +
+
+"type": "Property", +
+
+"value": "urn:ngsi-ld:null" +
+
+} +
+
+} +
+
+ +
+
+

5.5 Common +Behaviours

+

5.5.1 Introduction

+

This clause defines common behaviours for the API operations.

+

When comparing URIs, implementations shall follow the recommendations +of IETF RFC 3986 [5], +section 6.

+

5.5.2 Error types

+

Table +5.5.2‑1 details a list of error types defined by NGSI-LD. The +particular conditions under which error type shall be raised are defined +when describing each operation supported by the API.

+
+Table 5.5.2-1: Error types in NGSI-LD +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Error Type +
+Description +
+https://uri.etsi.org/ngsi-ld/errors/InvalidRequest +
+The request associated to the operation is syntactically invalid or +includes wrong content +
+https://uri.etsi.org/ngsi-ld/errors/BadRequestData +
+The request includes input data which does not meet the requirements of +the operation +
+https://uri.etsi.org/ngsi-ld/errors/AlreadyExists +
+The referred element already exists +
+https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported +
+The operation is not supported +
+https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound +
+The referred resource has not been found +
+https://uri.etsi.org/ngsi-ld/errors/InternalError +
+There has been an error during the operation execution +
+https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery +
+The query associated to the operation is too complex and cannot be +resolved +
+https://uri.etsi.org/ngsi-ld/errors/TooManyResults +
+The query associated to the operation is producing so many results that +can exhaust client or server resources. It should be made more +restrictive +
+https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable +
+A remote JSON-LD @context referenced in a request cannot be retrieved by +the NGSI-LD Broker and expansion or compaction cannot be performed +
+https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport +
+The NGSI-LD API implementation does not support multiple tenants +
+https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant +
+The addressed tenant does not exist +
+

5.5.3 Error +response payload body

+

When reporting errors back to clients, NGSI-LD implementations shall +generate a JSON object in accordance with IETF RFC 7807 [10], section 3.1, including, +at least the following terms:

+
    +
  • +type: Error type as per clause +5.5.2. +
    • +
  • +title: Error title which shall be a short string +summarizing the error. +
    • +
  • +detail: A detailed message that should convey enough +information about the error. +
    • +
+

Even though IETF RFC 7807 [10] defines a specific MIME +type for error payloads, NGSI-LD implementations shall use the standard +JSON MIME type ("application/json") when +reporting errors, so that old clients or existing tools are not +broken.

+
+EXAMPLE: +
+
+
+{ +
+
+"type": "https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound", +
+
+"title": "Resource not found.", +
+
+"detail": "urn:ngsi-ld:Device:widget001 was not found", +
+
+"status": 404, +
+
+"instance": "urn:ngsi-ld:Device:widget001" +
+
+} +
+
+

5.5.4 General +NGSI-LD validation

+

All the operations that take a JSON-LD document as input shall +process such JSON-LD document as follows:

+
    +
  • +If the request payload body is not a valid JSON document then an error +of type InvalidRequest shall be raised. +
    • +
  • +If the data included by the JSON-LD document is not syntactically +correct, according to the @context or the API data type +definitions, then an error of type BadRequestData shall be +raised. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as +a first level member value ("<key>": "urn:ngsi-ld:null"), with the exception +of NGSI-LD Fragments (see clause +5.4) used in partial update and merge operations (as mandated by clause +5.5.8 and clause +5.5.12) or to represent deleted Properties in concise representation +as part of notifications, shall result in an error of type +BadRequestData. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as the right-hand +side of value in a Property, as the right-hand side of +object in a Relationship or to use {"@none": "urn:ngsi-ld:null"} as the right-hand +side of languageMap, with the exception of NGSI-LD Fragments (see +clause +5.4) used in update and merge operations (as mandated by clause +5.5.8 and clause +5.5.12) and the representation of deleted Properties, Relationships +or Language Properties in notifications and the temporal evolution, +shall result in an error of type BadRequestData. +
    • +
  • +Any attempt to use "urn:ngsi-ld:null" as the value of a key +value pair within a JSON object, which is the right-hand side of the +value of a Property, with the exception of NGSI-LD Fragments used +in merge operations (see clause +5.5.12), shall result in an error of type BadRequestData. +
    • +
+

5.5.5 Default +@context assignment

+

If the input provided by an API client does not include any +@context, then the implementation shall at minimum assign the +Core @context to such an input. In addition, the Context Broker implementation may allow +configuring a default user @context (with default terms), to be +used when no user @context is provided. The Core @context +shall always take precedence.

+

5.5.6 Operation +execution

+

When executing an operation if an unexpected error happens and the +operation cannot be completed, implementations shall raise an error of +type InternalError. This includes, as well, situations such as +database timeouts, etc.

+

If the NGSI-LD endpoint is not capable of executing the requested +operation, an error of type OperationNotSupported shall be +raised. This may happen in a distributed architecture where a Context Broker might not be able to store +Entities (only to forward queries to Context +Sources), and as a result, certain operations such as "Create +Entity" might not be supported.

+

When a query operation is so complex that cannot be resolved by an +NGSI-LD system, implementations shall raise an error of type +TooComplexQuery.

+

When a query operation is producing so many results that can +potentially exhaust client or server resources, or it can be just +impractical to be managed, implementations shall raise an error of type +TooManyResults. The threshold conditions used as criteria to +raise such error is up to each implementation.

+

When a remote JSON-LD @context referenced by an incoming +request is not available, implementations shall raise an error of type +LdContextNotAvailable. If the remote JSON-LD @context is +invalid, implementations shall raise an error of type +BadRequestData.

+

5.5.7 Term to URI expansion +or compaction

+

NGSI-LD API operations allow clients to use short-hand strings as +non-qualified names, particularly for Property, +Relationship or Type names and VocabProperty values. For instance, an API +client can refer to the term "Vehicle" as +a non-qualified type name. When executing API update-related operations, +NGSI-LD systems shall expand terms to URIs, in order to obtain and store +Fully Qualified Names. Likewise, when executing query-related +operations, NGSI-LD systems shall compact URIs (Fully Qualified Names) +to short terms in order to provide short-hand strings to context +consumers.

+

The term to URI expansion or compaction shall be performed using a +@context as described by the JSON-LD specification [2] (section 5.1), and in clause +4.4. In the absence of a user +@context, the term expansion or compaction shall be +performed according to clause +5.5.5.

+

For the avoidance of doubt, the @context used to perform +compaction or expansion of terms shall be the one provided by +each API call (or the default @context in its absence), +and not any other @context which might have been supplied +previously. For instance, when performing "Query Entity" operations (clause +5.7.2), the @context used to perform URI expansion and +compaction shall be the one provided by the request.

+

In case of HTTP binding via GET (clause 6.4.3.2) of the "Query +Entity" operation, this means using the JSON-LD Link Header as described +by the JSON-LD specification [2], section 6.2. In case of +HTTP binding via POST (clause 6.23.3.1), of the "Query Entity" +operation, this means giving the @context either via Link Header +or within the payload body, depending on the Content-Type Header being +"application/json" or "application/ld+json", respectively.

+

It is important to warn users that updating a @context could +lead to behaviour that might be perceived as inconsistent. If, for +instance, a fully qualified name that qualified a given short-hand name +is changed, from that moment onwards, the short-hand name is referencing +a different Attribute. This will effectively change the results of +queries that use the given short name, possibly not giving back anymore +the expected set of results.

+

Moreover, this user @context shall not:

+
    +

  • Contain JSON-LD Scoped Contexts (see [2], section 4.1.8).

    • +

  • Be embedded into NGSI-LD Attributes, i.e. there cannot be parts +of the user @context other than at the top level of the NGSI-LD +document.

    • +
+

Parts of user @context that are not following the two points +above should result in an error of type BadRequestData, because +JSON-LD Scoped Contexts and nested embedded @context could be +used to modify terms defined in the Core @context or to reshape NGSI-LD +Elements during the expansion of terms.

+

As the Core @context is protected and cannot be overridden, when +performing term to URI expansion or compaction, implementations +shall always consider the Core @context +as having absolute precedence, regardless of the +position of the Core @context in the @context array of +elements. Nonetheless, NGSI-LD data providers may use appropriate term +prefixing to ensure that a proper term to URI expansion or compaction is +performed.

+

At compaction time, in the event that no matching term is found in +the current @context, implementations shall render Fully +Qualified Names.

+
+EXAMPLE: An entity of type "Vehicle" bound +to a certain @context, C, will match a query by "Vehicle" type if and only if the supplied +query @context, Q, maps the term "Vehicle" to the same URI as C. +
+
+Note that the JsonProperty is designed to hold native JSON values +which are by definition not available for expansion and compaction via +an @context. Therefore the given short-hand name is always used +for accessing JSON keys within a JsonProperty json +element. +
+

5.5.8 Partial Update Patch +Behaviour

+

The Partial Update Patch procedure modifies an existing NGSI-LD +element by overwriting the data at the Attribute level, replacing it +with the data provided in the NGSI-LD Fragment.

+

When updating NGSI-LD elements (Entities, Context Source Registrations or Context +Subscriptions) using NGSI-LD Fragments, implementations shall determine +the exact set of changes being requested by comparing the content of the +provided Fragment (patch) against the current content (a JSON-LD object) +of the target element.

+

With respect to update operations, implementations shall perform an +algorithm equivalent to the one described below (adapted from IETF RFC +7396 [16]), in order +to observe the name to URI expansion rules and the JSON-LD null +processing):

+
    +
  • +For each member of the Fragment perform the term to URI expansion. +
    • +
  • +If the provided Fragment (a JSON Merge Patch document) contains members +that do not appear within the target (their URIs do not match), those +members are added to the target. +
    • +
  • +For each member of the Fragment contained by the target, the target +member value is replaced by the value given in the Fragment. In the case +of a member representing a reified Property or Relationship including a +datasetId, such member is only replaced if the datasetId +is the same, otherwise the member of the Fragment is added as a new +instance to the target. If no datasetId is present, the default +Attribute instance is targeted and replaced if present and otherwise +added. In case of a member type (of an entity) in Entity +Fragments, all included Entity Types are added, if they are not already +contained in the type member of the target. +
    • +
  • +For each member of the Fragment, whose value is an NGSI-LD Null, +contained by the target, the target member is deleted. In the case of +deleting a specific Attribute instance with a datasetId, the +handling shall be in accordance with the description found in clause +5.6.5. A datasetId cannot be deleted by setting it to the +value "urn:ngsi-ld:null". +
    • +
+
+EXAMPLE 1: Given an Entity containing the following Property: +
+
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+
+ Applying partial attribute update operation (as defined +in clause +5.6.4) at the Attribute level onto the temperature Attribute, +with the following Attribute Fragment payload: +
+
+
+{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+ +
+
+
+ Results in an overwrite of the value and observedAt +sub-Attributes, leaving the unitCode sub-Attribute untouched as +shown: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+EXAMPLE 2: Given an Entity containing the following Property: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+ Applying an update attributes operation (as defined in +clause +5.6.2) onto the Entity as a whole with the following Entity Fragment +payload: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+ Results in an overwrite of the whole temperature Attribute – +other Attributes would remain untouched. The result is that the +value and observedAt sub-Attributes are updated and the +unitCode sub-Attribute is removed as shown: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 100, +
+
+"observedAt": +"2022-03-14T13:00:00.000Z" +
+
+} +
+
+} +
+
+ +
+
+EXAMPLE 3: Given an Entity containing the following Property: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": 25, +
+
+"unitCode": +"CEL" +
+
+"observedAt": +"2022-03-14T01:59:26.535Z" +
+
+} +
+
+} +
+
+ +
+
+ Applying an update attributes operation (as defined in +clause +5.6.2) onto the Entity as a whole, with the following Entity +Fragment payload: +
+
+{ +
+
+"temperature": +{ +
+
+"type": +"Property", +
+
+"value": +"urn:ngsi-ld:null" +
+
+} +
+
+} +
+
+ +
+
+ Results in the deletion of the whole temperature Attribute – all +other Attributes remain untouched. +
+

5.5.9 Pagination +Behaviour

+

When resolving NGSI-LD Query operations, NGSI-LD Systems shall +exhibit the behaviour described by the present clause:

+
    +
  • +Let Md be equal to the default maximum number of +NGSI-LD Elements to be retrieved by the API during each query pagination +iteration, as defined by the NGSI-LD implementation. +
    • +
  • +Let Mc be equal to the maximum number of NGSI-LD +Elements to be retrieved as requested by the NGSI-LD Client. If +Mc is undefined then it shall be equal to +Md. +
    • +
  • +Let L be the maximum number of NGSI-LD Elements to be +retrieved by the API during each query pagination iteration. +L shall be equal to Mc. +
    • +
  • +During query execution and for each pagination iteration, the query +resolution mechanisms of the NGSI-LD System shall ensure that only up to +a maximum of L NGSI-LD Elements are retrieved and +returned to the NGSI-LD client, i.e. the maximum page size per iteration +shall not overpass L. Nonetheless, implementations +shall take care of not overpassing a maximum size of response payload +body, which, in practice, implies that, under certain circumstances, the +number of Elements retrieved per page can be lower than +L. +
    • +
  • +After the retrieval of each page (containing at most L NGSI-LD +Elements) implementations shall check whether there are pending +NGSI-LD Elements to be retrieved in the context of the current query. If +that is the case, implementations shall flag NGSI-LD Clients of the +existence of such NGSI-LD Elements. Ultimately, the flagging mechanisms +used shall depend on each API binding but shall be present as mandated +by the present clause. +
    • +
  • +When flagging the existence of additional NGSI-LD Elements (pages) +pending to be retrieved, generally, implementations shall provide +NGSI-LD Clients pointers to get access to both the following page of +NGSI-LD Elements and the previous one, according to the current +pagination iteration. +
    • +
  • +The pointer to the previous page of NGSI-LD Elements shall be included +for all pagination iterations excepting the first one, as, obviously, +there will be no previous NGSI-LD Elements. +
    • +
  • +When the last page of NGSI-LD Elements is reached, only the pointer to +the previous page shall be provided to NGSI-LD Clients, so that they can +detect that no more NGSI-LD Elements are available. +
    • +
  • +The pointers to NGSI-LD Elements shall contain all the parameters needed +to allow NGSI-LD Clients to retrieve the next and previous page, without +further interactions with the API. +
    • +
+

While iterating over a set of pages, there might be changes in the +target result set, due to additions or removals of NGSI-LD Elements +occurring in between. Implementations may detect those situations and +may warn NGSI-LD Clients appropriately.

+

5.5.10 Multi-Tenant Behaviour

+

If a Tenant is specified for an +NGSI-LD operation, the operation shall only be applied to information +related to the specified Tenant. If +no Tenant is specified, the operation +shall apply to the implicitly existing default Tenant. If a Tenant is explicitly specified, but the +system implementing the NGSI-LD API does not support multi-tenancy, an +error of type NoMultiTenantSupport should be raised.

+

In case an operation applies to a Tenant, this information shall also be +provided in the response to the operation. This also applies to +notifications sent as a result of subscriptions (clauses 5.8 +and 5.11).

+

A Tenant is represented in form of +a String. How the Tenant is specified +for an API operation is protocol binding specific. How Tenants +are created, is implementation-specific.

+

One implementation option is to support the implicit creation of +Tenants. This means that a Tenant is implicitly created when an +NGSI-LD operation for creating information targets a new Tenant; this is the case for:

+ +

All other NGSI-LD operations, e.g. for retrieving, updating, +appending or deleting information that target a non-existing Tenant should raise an error of type +NonexistentTenant.

+

If the system implementing the NGSI-LD API does not support multiple +Tenants, the attempt to register a Context Source with Tenant information in the Context Source Registration should also +result in an error of type NoMultiTenantSupport.

+

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

+

5.5.11.0 Foreword

+

The following operations operate on an array of entities (as input +payload):

+ +

It is allowed for such an input Entity array to contain more than one +instance of the same entity (those instances have identical ids).

+

In order for such a request to be correctly handled, those instances +that have the same id are processed by the Broker in the order +they have in the array: the higher the index in the array, the later it +will be processed. If the order is altered, the outcome may be +altered.

+

All Entities and Attributes in the batch will get the same +modifiedAt timestamp, so it makes sense to distinguish them via +the observedAt temporal property.

+

Implementations shall treat the entity instances as if they had all +arrived in separate requests.

+

The following clauses specify the behaviour in each case.

+

5.5.11.1 Batch Entity Creation +case

+

The first occurrence of an entity in the input array (the oldest one) +is used for the creation of the entity. Any subsequent instance of the +same entity is reported as an error (entity already exists) in the +response.

+

5.5.11.2 Batch Entity +Creation or Update (Upsert) case

+

This operation has two modes of operation, with an optional flag to +select between the two. The default behaviour is to replace any already +existing entities, while the optional behaviour is to update already +existing entities. Non existing entities are created in both modes.

+

If the entity does not yet exist, the first occurrence of an entity +is used to create the entity, and subsequent instances of that same +entity are used to either replace (default behaviour) or to update +(optional behaviour) the entity. These replace or update operations +shall be done in chronological order.

+

Only the entity resulting from merging all of the entity instances, +in the correct order, is maintained in the current state (as defined in +clause +4.3.1). For Temporal Evolution of +Entities (as defined in clause +4.3.1), all entity instances shall be taken into account, in the +correct order.

+

5.5.11.3 Batch Entity Update case

+

This operation has two modes of operation, with an optional flag to +select between the two. The default behaviour is to replace any already +existing attributes of the entities, while the optional behaviour is to +preserve already existing attributes of the entities.

+

Brokers shall send separate notifications for each individual update, +taking throttling into account.

+

5.5.11.4 Batch Entity Delete case

+

The Batch Entity Delete operation has as input an array of Entity +IDs, for the entities to be deleted. If an Entity ID is replicated in +the array, the first occurrence will delete the entity, while subsequent +occurrences of the same Entity ID will provoke an error in the response +(entity does not exist).

+

5.5.11.5 Batch Entity Merge case

+

The Batch Entity Merge operation has as input an array of Entity IDs, +for the entities to be merged. If an Entity ID is replicated in the +array, these merge operations shall be done in chronological +order. Only the entity resulting from merging all of the entity +instances, in the correct order, is maintained in the current state (as +defined in clause +4.3.1). For Temporal Evolution of +Entities (as defined in clause +4.3.1), all entity instances shall be taken into account, in the +correct order.

+

5.5.12 Merge +Patch Behaviour

+

The merge patch procedure modifies an existing NGSI-LD element by +applying the set of changes found in an NGSI-LD Fragment data to the +target resource. Unlike the partial update patch behaviour (described in +clause +5.5.8), which replaces the complete element on the first level, e.g. +a whole Attribute, the procedure described in this clause merges the +provided information with the existing information up to an arbitrary +depth, e.g. including going into JSON objects representing a Property +value.

+

When merging NGSI-LD Entities using NGSI-LD Fragments, +implementations shall determine the exact set of changes being requested +by comparing the content of the provided Fragment (patch) against the +current content (a JSON-LD object) of the target element.

+

With respect to merge operations, implementations shall perform an +algorithm equivalent to the one described below (adapted from IETF RFC +7396 [16], in order +to observe the name to URI expansion rules and JSON-LD null +processing):

+
    +
  • +For each member of the Fragment perform the term to URI expansion. +
    • +
  • +If the provided Fragment (a JSON Merge Patch document) contains members +that do not appear within the target (their URIs do not match), those +members are added to the target. +
    • +
  • +For each member of the Fragment contained by the target, the target +member value is merged with the value given in the +Fragment. NGSI-LD Nulls within the Fragment are given special meaning to +indicate the removal of existing values within the target member value. +In the case of a member representing a reified Property or Relationship +including a datasetId, such member is only updated if the +datasetId is the same, otherwise the member of the Fragment is +added as a new instance to the target. If no datasetId is +present, the default Attribute instance is targeted and merged if +present and otherwise added. In case of a member type (of an +Entity) in Entity Fragments, all included Entity Types are added, if +they are not already contained in the type member of the target. +
    • +
  • +For each member of the Fragment, whose value is an NGSI-LD Null, +contained by the target, the target member is removed. In the case of +deleting a specific Attribute instance with a datasetId, the +handling shall be according to the description in clause +5.6.5. A datasetId cannot be deleted by setting it to the +value "urn:ngsi-ld:null". +
    • +
+
+EXAMPLE 1: Given an Entity containing the following Property: +
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 25, +
+
+    "unitCode": "CEL" +
+
+    "observedAt": "2022-03-14T01:59:26.535Z" +
+
+  } +
+
+} +
+
+ +
+
+ Applying a merge entity operation (as defined in clause +5.6.17) onto the Entity as a whole, with the following Entity +Fragment payload: +
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 100, +
+
+    "observedAt": "2022-03-14T13:00:00.000Z" +
+
+  } +
+
+} +
+
+ +
+
+ Results in the update of the value and observedAt +sub-Attributes and leaves the unitCode sub-Attribute untouched, +as shown: +
+
+{ +
+
+  "temperature": { +
+
+    "type" : "Property", +
+
+    "value" : 100, +
+
+    "unitCode": "CEL", +
+
+    "observedAt": "2022-03-14T13:00:00.000Z" +
+
+  } +
+
+} +
+
+ +
+
+EXAMPLE 2: Given an Entity containing the following Property: +
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value" : { +
+
+          "street": "Straße des 17. Juni", +
+
+          "city": "Berlin", +
+
+          "country": "Germany" +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+ Applying a merge entity operation (as defined in clause +5.6.17) onto the Entity as a whole with the following Entity +Fragment payload: +
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value" : { +
+
+          "street": "Pariser Platz", +
+
+          "country": "urn:ngsi-ld:null" +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+ Results in the updating of the address Attribute value applying +the JSON Merge Patch processing rules as defined in IETF RFC 7396 +[16], updating +street and removing country resulting as shown: +
+
+{ +
+
+  "address": { +
+
+    "type" : "Property", +
+
+    "value": { +
+
+          "street": "Pariser Platz", +
+
+          "city": "Berlin" +
+
+    } +
+
+} +
+

5.5.13 Limiting operations to +local scope

+

The API provides a binding-specific mechanism to limit the execution +of operations to a local scope, i.e., to only execute it based on +information available in the Context Source or +Context Broker directly targeted by the request. This enables +limiting cascading distributed operations (clause +4.3.6.4) and, in some cases, also enables broader local operations, +e.g., pertaining to all entities, which would be too +expensive in the distributed case.

+

The localOnly +member in the Subscription (clause +5.5.12) requests that the subscription only matches Entities stored +locally.

+

The localOnly member in the +RegistrationManagementInfo (clause 5.2.34) of a Context Source Registration request that, +when contacting the registered ContextSource, a local scope shall +be specified. Thus, the registered Context Source only provides +its local information, not information from further +Context Sources in its own Context Registry.

+

If the request limits the execution of the operation to the local +scope, Context Source Registrations +from the Context Registry are not required and thus do not need +to be requested.

+

5.5.14 Distributed +Transactional Behaviour

+

The following operations may occur as part of a distributed +transactional request:

+ +

In the case that a client wishes to indicate to a Context Broker that a request is part of a +unitary sequence of requests, the Context +Broker shall create and cache an EntityMap for future use and +return the location of said EntityMap in a specific field. The caching +strategy and expiry time shall depend on implementation specific +configurations. Context Sources may +indicate that they do not support EntityMaps, through declining to +return the location of an EntityMap when requested to do so.

+

If a subsequent request references an existent EntityMap, it shall be +used for the purposes of Entity registration matching, and queries shall +be filtered to only consider the Entities listed. If an EntityMap has +expired, or cannot be accessed, no inference can be made as to which +entities are held within the Context Sources +and a new one shall be created. All data within an Entity Map is +fixed, and cannot be altered, except for the expiry timestamp of the +EntityMap, which can optionally be extended if the Context Sources implementation allows for +it.

+

5.6 Context +Information Provision

+

5.6.1 Create Entity

+

5.6.1.1 Description

+

This operation allows creating a new NGSI-LD Entity.

+

5.6.1.2 Use case +diagram

+

A Context Producer can create an +Entity within an NGSI-LD system as shown in Figure +5.6.1.2‑1.

+
+ +
+
+Figure 5.6.1.2-1: Create entity use case +
+

5.6.1.3 Input data

+

A JSON-LD document representing an NGSI-LD Entity as mandated by clause +5.2.4.

+

5.6.1.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI), Attributes +from matching input data are forwarded for remote processing: +
    • +
+
    +
  • +For matching Registrations where the Create Entity operation is +supported, the operation is forwarded to the registration endpoint. If +the endpoint then raises an error, this shall result in an error in case +the complete create failed or in a partial success if some parts of the +create succeeded. +
    • +
  • +For matching Registrations where the Create Entity operation is not +supported, this shall result in an error of type Conflict if the +complete Create Entity operation failed or in a partial success if some +parts of it succeeded. +
    +
    +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints: +
    • +
+
    +
  • +For matching Registrations where the Create Entity operation is +supported, matching input data is forwarded. If any such endpoint then +raises an error, this shall result in an error in case the complete +create has failed or in a partial success if some parts of the create +has succeeded. +
    • +
  • +For matching redirect Registrations where the Create +Entity operation is not supported, this shall result in an error of type +Conflict if the complete Create Entity operation failed or in a +partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing by +matching endpoints in case the Create Entity operation is supported. +
    • +
  • +If the Entity already exists locally this shall result in an error of +type AlreadyExists, if the complete Create Entity operation has +failed or in a partial success if some parts of it has succeeded. +
    • +
  • +Any remaining input data shall be used to create the Entity locally. +
    • +
+

5.6.1.5 Output data

+

None.

+

5.6.2 Update +Attributes

+

5.6.2.1 Description

+

This operation allows modifying an existing NGSI-LD Entity by +updating already existing Attributes (Properties or +Relationships) and by appending non-existing ones.

+

5.6.2.2 Use case +diagram

+

A Context Producer can update +Attributes within an NGSI-LD system as shown in Figure +5.6.2.2‑1.

+
+ +
+
+Figure 5.6.2.2-1: Update Attributes use case +
+

5.6.2.3 Input data

+
    +
  • +A URI representing the id of the Entity to be updated (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
+

5.6.2.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent to the target entity held locally, and no matching +registrations apply (see ), an error of type ResourceNotFound +shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded for +remote processing. For each matching registration: +
    • +
+
    +
  • +If the Update Attributes operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Update Attributes operation is not supported by the registration, +this shall result in an error of type Conflict if the complete +update failed or in a partial success if some parts of the update +succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +If there are remaining Attributes, for any inclusive +Context Source Registrations that +exist and match against the remaining input data, that input data is +also forwarded for remote processing to matching endpoints in case the +Update Attributes operation is supported by the matched registration. +
    • +
  • +Then, implementations shall perform a partial update patch operation +over the remains of the target Entity as mandated by clause +5.5.8, using the following procedure: +
    • +
  • +For each Attribute (Property or Relationship) included by the Entity +Fragment at root level: +
    • +
+
    +
  • +If the target Entity does not include a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7) then such Attribute shall be appended to the target Entity. +
    • +
  • +If the target Entity already includes a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7): +
    • +
+
    +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
+- If an Attribute instance in the target Entity has the same +datasetId and the Attribute value is not NGSI-LD Null, then the +existing Attribute instance with the specified datasetId in the +target Entity shall be replaced by the new one supplied. +
+
+- If an Attribute instance in the target Entity has the same +datasetId and the Attribute value is NGSI-LD Null then the +existing Attribute instance with the specified datasetId in the +target Entity shall be deleted. +
+
+- Otherwise the Attribute instance with the specified datasetId +shall be appended to the target Entity. +
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment, the default Attribute instance is targeted: +
    • +
+
+- If the default Attribute instance is present and the Attribute value is +not NGSI-LD Null, then the existing Attribute in the target +Entity shall be replaced by the new one supplied. +
+
+- If the default Attribute instance is present and the Attribute value is +NGSI-LD Null, then the existing Attribute in the target Entity +shall be deleted. +
+
+- Otherwise the default Attribute instance shall be appended to the +target Entity. +
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and the target entity +includes scope, replace the scope by the one included in the +Fragment, otherwise ignore it. +
    • +
+

5.6.2.5 Output data

+
    +
  • +A status code indicating whether all the new Attributes were updated or +only some of them. +
    • +
  • +List of Attributes (Properties or Relationships) actually updated. +
    • +
+

5.6.3 Append +Attributes

+

5.6.3.1 Description

+

This operation allows modifying an NGSI-LD Entity by adding new +attributes (Properties or Relationships).

+

5.6.3.2 Use case +diagram

+

A Context Producer can append new +Attributes to an existing Entity within an NGSI-LD system as shown in Figure +5.6.3.2‑1.

+
+ +
+
+Figure 5.6.3.2-1: Append Attributes use case +
+

5.6.3.3 Input data

+
    +
  • +A URI representing the id of the E to be modified (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
  • +An optional flag indicating whether overwriting existing Attributes +within the append operation should be permitted or denied. By default, +Attribute overwrites are permitted. +
    • +
+

5.6.3.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about this Entity, because there +is no existing Entity which id (URI), and where specified type, is +equivalent held locally to the one passed as a parameter, and no +matching registrations apply (see ), an error of type +ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Append Attributes operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Append Attributes operation is not supported by the registration, +this shall result in an error of type Conflict if the complete +append failed or in a partial success if some parts of the append +succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing to +matching endpoints in case the Append Attributes operation is supported. +
    • +
  • +Then, implementations shall perform an Append Attributes operation over +the remains of the target Entity as using the following procedure: +
    • +
  • +For each Attribute (Property or Relationship) included by the Entity +Fragment at root level: +
    • +
+
    +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
    +
  • +If no Attribute instance of the same target Entity exists that has the +same datasetId, then such an Attribute shall be appended to the +target Entity. +
    • +
  • +If an Attribute instance of the same target Entity exists that has the +same datasetId: +
    • +
+
+- If overwrite is allowed, then the existing Attribute with the specified +datasetId in the target Entity shall be replaced by the new one +supplied. +
+
+- If overwrite is not allowed, the existing Attribute with the specified +datasetId in the target Entity shall be left untouched. +
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment: +
    • +
+
    +
  • +If no default Attribute instance of the same target Entity exists, then +such Attribute shall be appended to the target Entity. +
    • +
  • +If a default Attribute instance of the same target Entity exists: +
    • +
+
+- If overwrite is allowed, then the existing default Attribute in the +target Entity shall be replaced by the new one supplied. +
+
+- If overwrite is not allowed the existing default Attribute in the +target Entity shall be left untouched. +
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and overwrite is allowed, +the scope of the target Entity will become the one included in the +Fragment. Otherwise, the Scopes in the Fragment that are not part of the +value of scope of the target Entity will be appended to the value +of the scope of the target Entity. If there is more than one +Scope, the value of scope is represented as a JSON array +containing all Scopes. +
    • +
+

5.6.3.5 Output data

+
    +
  • +A status code indicating whether all the new Attributes were appended or +only some of them. +
    • +
  • +List of Attributes (Properties and/or Relationships) actually appended. +
    • +
+

5.6.4 Partial +Attribute update

+

5.6.4.1 Description

+

This operation allows performing a partial update on an +NGSI-LD Entity's Attribute (Property or Relationship). A +partial update only changes the elements provided in an Entity Fragment, +leaving the rest as they are. This operation supports the deletion of +sub-Attributes but not the deletion of the whole Attribute itself.

+

5.6.4.2 Use case +diagram

+

A Context Producer can carry out a +partial Attribute update of an Entity within an NGSI-LD System as shown +in Figure +5.6.4.2‑1.

+
+ +
+
+Figure 5.6.4.2-1: Partial Attribute update use case +
+

5.6.4.3 Input data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be modified, identified +by a name. +
    • +
  • +A JSON-LD document representing an NGSI-LD Attribute Fragment. +
    • +
+

5.6.4.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not valid or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute is scope, then an error of type +BadRequestData shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Partial Attribute update operation is supported by the +registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Partial Attribute update operation is not supported by the +registration, this shall result in an error of type Conflict in +case the complete partial Attribute update failed, or in a partial +success if some parts of the partial Attribute update succeeded. +
    +
    +No further processing is required. +
    • +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints in case the Partial Attribute update operation is supported. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7, so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute: +
    • +
+
    +
  • +as a default instance in case no datasetId is present; +
    • +
  • +as an instance with the specified datasetId if present; +
    • +
+
+then an error of type ResourceNotFound shall be raised. +
+
    +
  • +Perform a partial update patch operation on the target Attribute +following the algorithm mandated by clause +5.5.8. If present in the provided NGSI-LD Entity Fragment, the type +of the Attribute has to be the same as the type of the targeted +Attribute fragment, i.e. it is not allowed to change the type of an +Attribute. +
    • +
+

5.6.4.5 Output data

+

None.

+

5.6.5 Delete +Attribute

+

5.6.5.1 Description

+

This operation allows deleting an NGSI-LD Attribute (Property or +Relationship). The Attribute itself and all its children shall be +deleted.

+

5.6.5.2 Use case +diagram

+

A Context Producer can delete a +specific Attribute within an NGSI-LD system as shown in Figure +5.6.5.2‑1.

+
+ +
+
+Figure 5.6.5.2-1: Delete Attribute use case +
+

5.6.5.3 Input data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +An optional parameter identifying the datasetId of the target +Attribute instance to be deleted. Otherwise the default Attribute +instance is targeted. +
    • +
  • +An optional flag deleteAll indicating whether also all target +Attribute instances with a datasetId are to be deleted. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.5.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data (see ), the input data is forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Delete Attribute operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Delete Attribute update operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete delete Attribute failed, or in a partial success if +some parts of the delete Attribute succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply, then an +error of type ResourceNotFound shall be raised. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints in case the Delete Attribute operation is supported by the +matched registration. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute then an error +of type ResourceNotFound shall be raised. +
    • +
  • +If the target Attribute is scope, remove the scope +Attribute from the target Entity. +
    • +
  • +If the deleteAll flag is set, remove all target Attribute +instances from the target Entity. +
    • +
  • +Otherwise: +
    • +
+
    +
  • +if a datasetId parameter is provided, remove only the target +Attribute instance from the given dataset whose datasetId matches +the parameter; +
    • +
  • +if no datasetId parameter is provided, remove the default target +Attribute instance from the target Entity. +
    • +
+

5.6.5.5 Output data

+

None.

+
+5.6.6 Delete Entity +
+

5.6.6.1 Description

+

This operation allows deleting an NGSI-LD Entity.

+

5.6.6.2 Use case +diagram

+

A Context Producer can completely +delete an Entity within an NGSI-LD system as shown in Figure +5.6.6.2‑1.

+
+ +
+
+Figure 5.6.6.2-1: Delete Entity use case +
+

5.6.6.3 Input data

+
    +
  • +Entity ID (URI) of the Entity to be deleted, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
+

5.6.6.4 Behaviour

+
    +
  • +If the target Entity ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or Context +Source Registration matches against the id, the request is +forwarded for remote processing. For each matching registration: +
    • +
+
    +
  • +If the Delete Entity operation is supported by the registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Delete Entity update operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete delete Entity failed, or in a partial success if some +parts of the delete Entity succeeded. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints. +
    • +
+
    +
  • +For matching Registrations where the Delete Entity operation is +supported (see clause +4.3.6), matching input data is forwarded. If any such endpoint then +raises an error, the implementation shall return with the error(s) +raised. +
    • +
  • +For matching redirect Registrations where the Delete +Entity operation is not supported, this shall result in an error of type +Conflict in case the complete delete Entity failed, or in a +partial success if some parts of the delete Entity succeeded. +
    • +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Delete +Entity operation is supported for remote processing by matching +endpoints. +
    • +
  • +The input data shall be used to remove the entity locally if it exists. +
    • +
+

5.6.6.5 Output +data

+

None.

+

5.6.7 Batch Entity +Creation

+

5.6.7.1 Description

+

This operation allows creating a batch of NGSI-LD Entities.

+

5.6.7.2 Use case +diagram

+

A Context Producer can create a +batch of NGSI-LD Entities within an NGSI-LD system as shown in Figure +5.6.7.2‑1.

+
+ +
+
+Figure 5.6.7.2-1: Create a batch of Entities use case +
+

5.6.7.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an NGSI-LD Entity as mandated by clause 5.2.4. +See clause +5.5.11.1 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
+

5.6.7.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity successfully created. S shall be initialized to the empty +array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    +
      +
    • +Let IN be a copy of the original input array. +
      • +
    • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
      • +
    • +If IN is empty, continue with the next Context Source Registration if there is +any. +
      • +
    • +If the Batch Entity Creation operation is supported by CSR: +
      +
        +
      • +Forward the Batch Entity Creation request with IN as input Array. +
        • +
      • +Merge the returned list of Entities successfully created with S. +
        • +
      • +Merge the returned list of Entities in Error with E. +
        • +
      • +
    • +Otherwise, if the Create Entity operation (clause +5.6.1) is supported by CSR: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward a Create Entity request for Entity EN. +
          • +
        • +Merge any successful result(s) for Entity EN created with S. +
          • +
        • +Merge any error result(s) for Entity EN created with E. +
          • +
        • +
      • +
    • +Otherwise +
      +
        +
      • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
        • +
      • +
    • +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.1, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully created, then add the corresponding +Entity ID to the S array. +
    • +
  • +If the Entity creation failed, then a new BatchEntityError shall +be added to E containing the failed Entity ID and the related +ProblemDetails. +
    • +
+

5.6.7.5 Output data

+
    +
  • +the list of Entities successfully created (S Array), if all Entities +were created correctly; or +
    • +
  • +the list of Entities successfully created (S Array) and the list of +Entities in error (E Array), if only some or none of the Entities were +created. +
    • +
+

5.6.8 Batch Entity +Creation or Update (Upsert)

+

5.6.8.1 Description

+

This operation allows creating a batch of NGSI-LD Entities, updating +each of them if they already existed. In some database jargon this kind +of operation is known as "upsert".

+

5.6.8.2 Use case +diagram

+

A Context Producer can create or +update a batch of Entities within an NGSI-LD system as shown in Figure +5.6.8.2‑1.

+
+ +
+
+Figure 5.6.8.2-1: Upsert a batch of Entities use case +
+

5.6.8.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.2 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
  • +An optional flag indicating the update mode (only applies in case the +Entity already exists): +
    • +
+
    +
  • +Replace. All the existing Entity content shall be replaced (default +mode). +
    • +
  • +Update. Existing Entity content shall be updated. +
    • +
+

5.6.8.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +to the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    +
      +
    • +Let IN be a copy of the original input array. +
      • +
    • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
      • +
    • +If IN is empty, continue with the next Context Source Registration if there is +any. +
      • +
    • +If the Batch Entity Creation or Update (Upsert) operation is supported +by CSR: +
      +
        +
      • +Forward the Batch Entity Creation or Update (Upsert) request with IN as +input Array. +
        • +
      • +Merge the returned list of Entities successfully created with S. +
        • +
      • +Merge the returned list of Entities in Error with E. +
        • +
      • +
    • +Otherwise, if the Create Entity operation (clause +5.6.1) is supported by CSR: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward a Create Entity request for Entity EN. +
          • +
        • +If an error of type AlreadyExists is returned: +
          +
            +
          • +If the Replace Entity operation (clause +5.6.18) is supported by CSR and the value of the update mode flag is +Replace or the flag is not set, forward a Replace Entity request +for Entity EN. +
            • +
          • +Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and the value of the update mode flag is +Update, forward an Update Attributes request for Entity EN. +
            • +
          • +Otherwise add an OperationNotSupported Error for Entity EN +related to CSR to E. +
            • +
          • +
        • +Merge any successful result(s) for Entity EN created or updated with S. +
          • +
        • +Merge any error result(s) for Entity EN created or updated with E. +
          • +
        • +
      • +
    • +Otherwise, if the Replace Entity operation (clause +5.6.18) is supported by CSR and the value of the update mode flag is +Replace or the flag is not set: +
      +
        +
      • +Forward a Replace Entity request for Entity EN. +
        • +
      • +Merge any successful result(s) for Entity EN updated with S. +
        • +
      • +Merge any error result(s) for Entity EN updated with E. +
        • +
      • +
    • +Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and the value of the update mode flag is +Update: +
      +
        +
      • +Forward an Update Attributes request for Entity EN. +
        • +
      • +Merge any successful result(s) for Entity EN updated with S. +
        • +
      • +Merge any error result(s) for Entity EN updated with E. +
        • +
      • +
    • +Otherwise +
      +
        +
      • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
        • +
      • +
    • +
  • +For each of the NGSI-LD Entities included in the input Array +implementations shall: +
    • +
+
    +
  • +Create the Entity locally if it does not exist (i.e. no Entity with the +same Entity ID is present) executing the behaviour defined by clause +5.6.1, but limited to a local operation. +
    • +
  • +If there were an existing Entity with the same Entity ID, it shall be +completely replaced by the new Entity content provided, if the requested +update mode is 'replace'. +
    • +
  • +If there were an existing Entity with the same Entity ID, the behaviour +defined by clause +5.6.3 shall be executed, but limited to a local operation, if the +requested update mode is "update". +
    • +
+
    +
  • +If successful, the local creation or update shall be added to S. If +while processing an Entity there is any kind of error or abnormal +situation, a BatchEntityError shall be added to E containing the +failed Entity ID and the related ProblemDetails. +
    • +
+

5.6.8.5 Output data

+
    +
  • +none (if all Entities already existed and are successfully updated); or +
    • +
  • +the list of Entities successfully created (S Array), if all Entities not +existing prior to this request have been successfully created and the +others have been successfully updated; or +
    • +
  • +the list of Entities successfully created or updated (S Array), and the +list of Entities in error (E Array), if only some or none of the +Entities have been successfully created or updated. +
    • +
+

5.6.9 Batch Entity +Update

+

5.6.9.1 Description

+

This operation allows updating a batch of NGSI-LD Entities.

+

5.6.9.2 Use case +diagram

+

A Context Producer can update a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.9.2‑1.

+
+ +
+
+Figure 5.6.9.2-1: Update a batch of Entities use case +
+

5.6.9.3 Input data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.3 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
  • +An optional flag indicating whether Attributes shall be overwritten or +not. By default, Attributes will be overwritten. +
    • +
+

5.6.9.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +as the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized as the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    +
      +
    • +Let IN be a copy of the original input array. +
      • +
    • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
      • +
    • +Remove all Entities without Attributes from IN. +
      • +
    • +If IN is empty, continue with the next Context Source Registration if there is +any. +
      • +
    • +If the Batch Entity Update operation is supported by CSR: +
      +
        +
      • +Forward the Batch Entity Update request with IN as input Array. +
        • +
      • +Merge the returned list of Entities successfully created with S. +
        • +
      • +Merge the returned list of Entities in Error with E. +
        • +
      • +
    • +Otherwise, if the Update Attributes operation (clause +5.6.2) is supported by CSR and Attribute overwrite is permitted: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward an Update Attributes request for Entity EN. +
          • +
        • +Merge any successful result(s) for Entity EN updated with S. +
          • +
        • +Merge any error result(s) for Entity EN updated with E. +
          • +
        • +
      • +
    • +Otherwise, if the Append Attributes operation (clause +5.6.3) is supported by CSR and Attribute overwrite is not permitted: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward an Append Attributes request for Entity EN with Attribute +overwrite disabled: +
          • +
        • +Merge any successful result(s) for Entity EN updated with S. +
          • +
        • +Merge any error result(s) for Entity EN updated with E. +
          • +
        • +
      • +
    • +Otherwise +
      +
        +
      • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
        • +
      • +
    • +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.3, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully updated (Attributes appended), then add +the corresponding Entity ID to the S array. +
    • +
  • +If the Entity update failed, then a new BatchEntityError shall be +added to E containing the failed Entity ID and the ProblemDetails +associated. +
    • +
+

5.6.9.5 Output data

+
    +
  • +none (if all Entities are successfully updated); or +
    • +
  • +the list of Entities successfully updated (S Array), and the list of +Entities in error (E Array), if only some or none of the Entities have +been successfully updated. +
    • +
+

5.6.10 Batch Entity +Delete

+

5.6.10.1 Description

+

This operation allows deleting a batch of NGSI-LD Entities.

+

5.6.10.2 Use case +diagram

+

A Context Producer can delete a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.10.2‑1.

+
+ +
+
+Figure 5.6.10.2-1: Delete a batch of Entities use case +
+

5.6.10.3 Input data

+
    +
  • +A JSON-LD Array containing a list of Entity IDs (URIs) that are +requested to be deleted. See clause +5.5.11.4 for information on behaviour when there is more than one +instance of the same Entity ID in the input Array. +
    • +
+

5.6.10.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +If the input Array is empty or contains a null value in any of +its items, an error of type BadRequestData shall be raised. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +to the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized to the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    +
      +
    • +Let IN be a copy of the original input array. +
      • +
    • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
      • +
    • +Remove all Entities without Attributes from IN. +
      • +
    • +If IN is empty, continue with the next Context Source Registration if there is +any. +
      • +
    • +If the Batch Entity Delete operation is supported by CSR: +
      +
        +
      • +Forward the Batch Entity Delete request with IN as input Array. +
        • +
      • +Merge the returned list of Entities successfully created with S. +
        • +
      • +Merge the returned list of Entities in Error with E. +
        • +
      • +
    • +Otherwise, if the Delete Entity operation ) is supported by CSR: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward a Delete Entity request for Entity EN. +
          • +
        • +Merge any successful result(s) for Entity EN deleted with S. +
          • +
        • +Merge any error result(s) for Entity EN deleted with E. +
          • +
        • +
      • +
    • +Otherwise +
      • +
    • +
  • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
    • +
  • +For each of the NGSI-LD Entity IDs included in the input Array execute +the behaviour defined by , but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity corresponding to an Entity ID was successfully deleted, +then add such Entity ID to the S array. +
    • +
  • +If the Entity deletion failed, then a new BatchEntityError shall +be added to E containing the failed Entity ID and the related +ProblemDetails. +
    • +
+

5.6.10.5 Output +data

+
    +
  • +none (if all Entities that already existed are successfully deleted); or +
    • +
  • +the list of Entities successfully deleted (S Array), and the list of +Entities in error (E Array), if some or all of the Entities have not +been successfully deleted. +
    • +
+

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

+

5.6.11.1 Description

+

This operation allows creating or updating (by adding new Attribute +instances) the Temporal Evolution of an +Entity.

+

5.6.11.2 Use case +diagram

+

A Context Producer can create the +Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.11.2‑1.

+

Similarly, if the Entity already exists then an Update scenario will +be in place.

+
+ +
+
+Figure 5.6.11.2-1: Create or Update (Upsert) Temporal Evolution of an +Entity use case +
+

5.6.11.3 Input +data

+

A JSON-LD document representing the Temporal Evolution of an +Entity as mandated by clause +5.2.20.

+

5.6.11.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI), Attributes +from matching input data are forwarded for remote processing: +
    • +
+
    +
  • +For matching Registrations where the “Create or Update (Upsert) Temporal +Evolution of an Entity” operation is supported, the operation is +forwarded to the registration endpoint. If the endpoint then raises an +error, this shall result in an error in case the complete “Create or +Update (Upsert) Temporal Evolution of an Entity” operation failed or in +a partial success if some parts of it succeeded. +
    • +
  • +For matching Registrations where the “Create Entity” operation is not +supported, this shall result in an error of type Conflict in case +the complete “Create or Update (Upsert) Temporal Evolution of an Entity” +operation failed or in a partial success if some parts of it succeeded. +
    +
    +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
+
    +
  • +If any redirect Context +Source Registrations exist that match against the input data, +that input data is forwarded for remote processing by one or more +matching endpoints: +
    • +
+
    +
  • +For matching Registrations where the “Create or Update (Upsert) Temporal +Evolution of an Entity” operation is supported, matching input data is +forwarded. If any such endpoint then raises an error, this shall result +in an error in case the complete “Create or Update (Upsert) Temporal +Evolution of an Entity” operation failed or in a partial success if some +parts of it succeeded. +
    • +
  • +For matching redirect Registrations where the “Create +or Update (Upsert) Temporal Evolution of an Entity” operation is not +supported, this shall result in an error of type Conflict in case +the complete “Create or Update (Upsert) Temporal Evolution of an Entity” +operation failed or in a partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing by +matching endpoints. +
    • +
  • +If the NGSI-LD endpoint already knows about this Temporal Evolution of an +Entity, because there is an existing Temporal Evolution of an +Entity whose id (URI) is the same, then all the Attribute +instances included by the Temporal Evolution shall be added to the +existing Entity as mandated by clause +5.6.12. If type is included in the EntityTemporal Fragment +and it includes Entity Type names that are not yet in the target Temporal Evolution of an +Entity, add them to the list of Entity Type names of the target +Temporal Evolution of +anEntity. +
    • +
  • +Otherwise, implementations shall create the provided Temporal Evolution of an +Entity. +
    • +
+

5.6.11.5 Output +data

+

None.

+

5.6.12 Add +Attributes to Temporal Evolution of an Entity

+

5.6.12.1 Description

+

This operation allows modifying the Temporal Evolution of an +Entity by adding new Attribute instances.

+

5.6.12.2 Use case +diagram

+

A Context Producer can add new +Attributes or Attribute instances to an existing Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.12.2‑1.

+
+ +
+
+Figure 5.6.12.2-1: Add Attributes to Temporal Evolution of an Entity use +case +
+

5.6.12.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an +Entity to be modified with additional Attributes. +
    • +
  • +A JSON-LD document representing an NGSI-LD Fragment of +EntityTemporal, including only the new Attribute instance(s), and +contained by an Array. +
    • +
+

5.6.12.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Temporal Evolution of +an Entity, because there is no existing Temporal Evolution of an +Entity whose id (URI) is equivalent to the one passed as a +parameter held locally and no matching registrations apply, an error of +type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the Attributes from matching input data are forwarded +for remote processing. For each matching registration: +
    • +
+
    +
  • +If the “Add Attributes to Temporal Evolution of an Entity” operation is +supported by the matched registration, matching input data is forwarded +to the Registration endpoint. +
    • +
  • +If the “Add Attributes to Temporal Evolution of an Entity” operation is +not supported by the matched registration, this shall result in an error +of type Conflict if the complete “Add Attributes to Temporal +Evolution of an Entity” operation +failed or in a partial success if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded for remote processing to +matching endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally and +matches against the remaining input data, implementations shall do the +following: +
    • +
  • +For each Attribute (Property or Relationship) instance included by the +EntityTemporal Fragment at root level: +
    • +
+
    +
  • +The Attribute (considering term expansion rules as mandated by clause +5.5.7) instance(s) shall be added to the target Temporal Evolution of an Entity. +
    • +
+
    +
  • +If type is included in the EntityTemporal Fragment and it +includes Entity Type names that are not yet in the target Temporal Evolution of an +Entity, add them to the list of Entity Type names of the target +Temporal Evolution of +theEntity. +
    • +
+

5.6.12.5 Output +data

+

None.

+

5.6.13 Delete +Attribute from Temporal Evolution of an Entity

+

5.6.13.1 Description

+

This operation allows deleting an Attribute (Property or +Relationship) of the Temporal Evolution of an +Entity. The Attribute itself and all its child NGSI-LD elements +shall be deleted.

+

5.6.13.2 Use case +diagram

+

A Context Producer can delete a +specific Attribute of the Temporal +Evolution of an Entity within an NGSI-LD system as +shown in Figure +5.6.13.2‑1.

+
+ +
+
+Figure 5.6.13.2-1: Delete Attribute from Temporal Evolution of an Entity +use case +
+

5.6.13.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be modified by removing the +target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +An optional parameter identifying the dataset (datasetId) of the +target Attribute instance to be deleted. +
    • +
  • +An optional parameter, a flag, (deleteAll) indicating whether all +target Attribute instances are to be deleted, regardless of +datasetId. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.13.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Temporal Evolution of an +Entity whose id (URI) is equivalent held locally and no matching +registrations apply, then an error of type ResourceNotFound shall +be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the “Delete Attribute from Temporal Evolution of an Entity” operation +is supported by the matched registration, matching input data is +forwarded to the Registration endpoint. +
    • +
  • +If the “Delete Attribute from Temporal Evolution of an Entity” operation +is not supported by the matched registration, this shall result in an +error of type Conflict in case the complete “Delete Attribute +from Temporal Evolution of an Entity” failed, or in a partial success if +some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Temporal Evolution of an +Entity does not contain the +target Attribute then an error of type ResourceNotFound shall be +raised. +
    • +
  • +If the deleteAll flag is set, remove all target Attribute +instances from the target Entity. +
    • +
  • +Otherwise: +
    • +
+
    +
  • +if a datasetId parameter is provided, remove only any target +Attribute instance from the given dataset; +
    • +
  • +if no datasetId parameter is provided, remove only the default +target Attribute instance datasetId from the target Entity. +
    • +
+

5.6.13.5 Output +data

+

None.

+

5.6.14 Modify +Attribute instance in Temporal Evolution of an Entity

+

5.6.14.1 Description

+

This operation allows modifying a specific Attribute (Property or +Relationship) instance, identified by its instanceId, of the +Temporal Evolution of an +Entity.

+

This operation enables the correction of wrong information that could +have been previously added to the Temporal +Evolution of an Entity.

+

5.6.14.2 Use case +diagram

+

A Context Producer can modify a +specific Attribute instance, identified by a given instanceId, of +the Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.14.2‑1.

+
+ +
+
+Figure 5.6.14.2-1: Modify Attribute Instance in Temporal Evolution of an +Entity use case +
+

5.6.14.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be modified by changing an +instance of the target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be modified, identified +by a name. +
    • +
  • +Attribute instance to be modified, identified by its instanceId. +
    • +
  • +A JSON-LD document representing an NGSI-LD Fragment of +EntityTemporal, including only the new Attribute instance, +contained by an Array of exactly one item. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.14.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the target instanceId is not a valid URI or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the “Modify Attribute instance in Temporal Evolution of an Entity” +operation is supported by the matched registration, matching input data +is forwarded to the Registration endpoint. +
    • +
  • +If the “Modify Attribute instance in Temporal Evolution of an Entity” +operation is not supported by the matched registration, this shall +result in an error of type Conflict in case the complete Modify +Attribute instance in Temporal Evolution of an +Entity operation failed, or in a partial success if some parts of +it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Temporal Evolution of an +Entity does not contain the +target Attribute then an error of type ResourceNotFound shall be +raised. +
    • +
  • +If for the target Attribute no instance with the specified +instanceId exists, an error of type ResourceNotFound shall +be raised. +
    • +
  • +Replace the target Attribute instance identified by the +instanceId with the Attribute instance in the +EntityTemporal Fragment. The createdAt property of the +concerned instance shall remain unchanged, but the modifiedAt +property shall be set to the timestamp corresponding to this +modification. +
    • +
+

5.6.14.5 Output +data

+

None.

+

5.6.15 Delete +Attribute instance from Temporal Evolution of an Entity

+

5.6.15.1 Description

+

This operation allows deleting one Attribute instance (Property or +Relationship), identified by its instanceId, of the Temporal Evolution of an +Entity. The Attribute itself and all its child elements shall be +deleted. This operation enables the removal of individual Attribute +instances that could have been previously added to the Temporal Evolution of an +Entity.

+

5.6.15.2 Use case +diagram

+

A Context Producer can delete an +Attribute instance, identified by a given instanceId, of the +Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.15.2‑1.

+
+ +
+
+Figure 5.6.15.2-1: Delete Attribute Instance from Temporal +Evolution
+of an Entity use case +
+

5.6.15.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolutionof an Entity to be modified by deleting an +instance of the target Attribute. +
    • +
  • +Target Attribute (Property or Relationship) to be deleted, identified by +a name. +
    • +
  • +Attribute instance to be deleted, identified by its instanceId. +
    • +
  • +An optional JSON-LD @context. +
    • +
+

5.6.15.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not a valid name or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the target instanceId is not a valid URI or it is not present, +then an error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the “Delete Attribute instance from Temporal Evolution of an Entity” +operation is supported by the matched registration, matching input data +is forwarded to the Registration endpoint. +
    • +
  • +If the “Delete Attribute instance from Temporal Evolution of an Entity” +operation is not supported by the matched registration, this shall +result in an error of type Conflict in case the complete “Delete +Attribute instance from Temporal Evolution of an Entity” failed, or in a +partial success if some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, +implementations shall do the following: +
    • +
  • +Apply term expansion as mandated by clause +5.5.7 so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Temporal Evolution of +the Entity does not contain the target Attribute then an error of +type ResourceNotFound shall be raised. +
    • +
  • +If for the target Attribute no instance with the specified +instanceId exists, an error of type ResourceNotFound shall +be raised. +
    • +
  • +Remove the instance, with the specified instanceId, of the target +Attribute from the target Entity. +
    • +
+

5.6.15.5 Output +data

+

None.

+

5.6.16 Delete Temporal +Evolution of an Entity

+

5.6.16.1 Description

+

This operation allows deleting the Temporal Evolution of an +Entity.

+

5.6.16.2 Use case +diagram

+

A Context Producer can completely +delete the Temporal Evolution of an +Entity within an NGSI-LD system as shown in Figure +5.6.16.2‑1.

+
+ +
+
+Figure 5.6.16.2-1: Delete Temporal Evolution of an Entity use case +
+

5.6.16.3 Input +data

+
    +
  • +Entity ID (URI) of the target Temporal +Evolution of an Entity to be deleted. +
    • +
+

5.6.16.4 Behaviour

+
    +
  • +If the target Entity ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity because +there is no existing Entity whose id (URI) is equivalent held locally +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the “Delete Temporal Evolution of Entity” operation is supported by +the matched registration, matching input data is forwarded to the +Registration endpoint. +
    • +
  • +If the “Delete Temporal Evolution of Entity” operation is not supported +by the matched registration, this shall result in an error of type +Conflict in case the complete “Delete Temporal Evolution of +Entity” failed, or in a partial success if some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the input data, +that input data is also forwarded for remote processing to matching +endpoints. +
    • +
  • +If the target Temporal Evolution of an +Entity exists locally, the +entire Temporal Evolution of +the Entity shall be removed. +
    • +
+

5.6.16.5 Output +data

+

None.

+

5.6.17 Merge Entity

+

5.6.17.1 Description

+

This operation allows modification of an existing NGSI-LD Entity +aligning to the JSON Merge Patch processing rules defined in IETF RFC +7396 [16] by adding +new Attributes (Properties or Relationships) or modifying or deleting +existing Attributes associated with an existing Entity.

+

5.6.17.2 Use case +diagram

+

A Context Producer can perform a +merge on an Entity within an NGSI-LD system as shown in Figure +5.6.17.2‑1.

+
+ +
+
+Figure 5.6.17.2-1: Merge Entity use case +
+

5.6.17.3 Input +data

+
    +
  • +A URI representing the id of the Entity to be merged (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity Fragment. +
    • +
  • +An optional flag indicating whether the JSON-LD document contains a +simplified representation of the entity. +
    • +
  • +An optional parameter indicating a common observedAt timestamp to +use across merged Attributes. +
    • +
  • +An optional parameter representing a common IETF RFC 5646 [28] language tag to use +across merged LanguageMap Attributes. +
    • +
+

5.6.17.4 Behaviour

+

The following behaviour shall be exhibited by compliant +implementations:

+
    +
  • +If the Entity ID is not present or it is not a valid URI then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Merge Entity operation is supported by the matched registration +(see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Merge Entity operation is not supported by the matched +registration, this shall result in an error of type Conflict in +case the complete Merge Entity operation failed, or in a partial success +if some parts of it succeeded. +
    • +
+
+ The matching Attributes are then removed from the Fragment and not +processed further. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Merge +Entity operation is supported for remote processing to matching +endpoints. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls should be supported by +this operation. If NGSI-LD Nulls are found in the payload, but are not +supported, an error of type OperationNotSupported shall be +raised. +
    • +
+
+ Then, implementations shall perform a merge operation over the target +Entity as mandated by clause +5.5.12, using the following procedure: +
+
+ For each Attribute (Property or Relationship) included by the Entity +Fragment: +
+
    +
  • +If the target Entity does not include a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7), then such Attribute shall be appended to the target Entity. +
    • +
  • +If the target Entity already includes a matching Attribute (considering +term expansion rules as mandated by clause +5.5.7): +
    • +
+
    +
  • +If the Attribute (Property or Relationship) to be merged is represented +in a simplified representation, the type of any pre-existing +Attribute in the target entity shall be preserved. +
    • +
  • +If a common language tag is defined and a LanguageProperty +Attribute to be merged is represented as a string, the pre-existing +languageMap JSON object shall be preserved. The string value +shall only replace the value associated to the language tag key found +within the languageMap. +
    • +
  • +If a common observedAt timestamp is defined and an existing +Attribute to be merged previously contained an observedAt +sub-Attribute, the observedAt sub-Attribute is also updated using +the common timestamp, unless the Entity Fragment itself contains an +explicit updated value for the observedAt sub-Attribute. +
    • +
  • +If a datasetId is present in the Attribute included by the Entity +Fragment: +
    • +
+
+- If an Attribute instance in the target Entity has the same +datasetId: +
+
+- If overwrite is allowed and the Attribute value is not NGSI-LD Null, +then the existing Attribute with the specified datasetId in the +target Entity shall be merged with the new one supplied. +
+
+- If overwrite is allowed and the Attribute value is NGSI-LD Null, then +the existing Attribute with the specified datasetId in the target +Entity shall be deleted. +
+
+- If overwrite is not allowed, the existing Attribute with the specified +datasetId in the target Entity shall be left untouched. +
+
+- Otherwise the Attribute instance with the specified datasetId +shall be appended to the target Entity. +
+
    +
  • +If no datasetId is present in the Attribute included by the +Entity Fragment, the default Attribute instance is targeted: +
    • +
+
+- If the default Attribute instance is present: +
+
+- If overwrite is allowed and the Attribute value is not NGSI-LD Null, +then the existing Attribute in the target Entity shall be merged with +the new one supplied. +
+
+- If overwrite is allowed and the Attribute value is NGSI-LD Null, then +the existing Attribute with the specified datasetId in the target +Entity shall be deleted. +
+
+- If overwrite is not allowed, the existing Attribute in the target +Entity shall be left untouched. +
+
+- Otherwise if value is not NGSI-LD Null, the default Attribute instance +shall be appended to the target Entity. +
+
    +
  • +If type is included in the Fragment and it includes Entity Type +names that are not yet in the target Entity, add them to the list of +Entity Type names of the target Entity. +
    • +
  • +If scope is included in the Fragment and overwrite is allowed, +the scope of the target Entity will become the one included in the +Fragment. Otherwise, the Scopes in the Fragment that are not part of the +value of scope of the target Entity will be appended to the value +of the scope of the target Entity. If there is more than one +Scope, the value of scope is represented as a JSON array +containing all Scopes. +
    • +
+

5.6.17.5 Output +data

+
    +
  • +A status code indicating whether all the Attributes were merged +successfully. +
    • +
  • +List of Attributes (Properties and/or Relationships) actually merged. +
    • +
+

5.6.18 Replace +Entity

+

5.6.18.1 Description

+

This operation allows the modification of an existing NGSI-LD Entity +by replacing all of the Attributes (Properties or Relationships).

+

5.6.18.2 Use case +diagram

+

A Context Producer can replace an +entire Entity within an NGSI-LD system as shown in Figure +5.6.18.2‑1.

+
+ +
+
+Figure 5.6.18.2-1: Replace Entity use case +
+

5.6.18.3 Input +data

+
    +
  • +A URI representing the id of the Entity to be replaced (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +A JSON-LD document representing an NGSI-LD Entity. +
    • +
+

5.6.18.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI or it is not present, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. NGSI-LD Nulls are not supported by this +operation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, Attributes from matching input data are forwarded. For +each matching registration: +
    • +
+
    +
  • +If the Replace Entity operation is supported by the registration (see clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Replace Entity operation is not supported by the registration, +this shall result in an error of type Conflict in case the +complete Replace Entity operation failed, or in a partial success if +some parts of it succeeded. +
    • +
+
    +
  • +The matching Attributes are then removed from the Fragment and not +processed further. +
    • +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Replace +Entity operation is supported for remote processing to matching +endpoints. +
    • +
  • +If the target Entity exists locally, completely replace the existing +Entity with the same Entity ID with the new Entity content provided. The +system generated createdAt Temporal Property of the Entity as +defined in clause +4.8 remain unchanged. +
    • +
+

5.6.18.5 Output +data

+

None.

+

5.6.19 Replace +Attribute

+

5.6.19.1 Description

+

This operation allows the replacement of a single Attribute (Property +or Relationship) within an NGSI-LD Entity.

+

5.6.19.2 Use case +diagram

+

A Context Producer can carry out a +replacement of an Attribute within an Entity within an NGSI-LD System as +shown in Figure +5.6.19.2‑1.

+
+ +
+
+Figure 5.6.19.2-1: Replace Attribute use case +
+

5.6.19.3 Input +data

+
    +
  • +Entity ID (URI) of the concerned Entity, the target Entity. +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +Target Attribute (Property or Relationship) to be replaced, identified +by a name. +
    • +
  • +A JSON-LD document representing an NGSI-LD Attribute Fragment. +
    • +
+

5.6.19.4 Behaviour

+
    +
  • +If the target Entity ID is not a valid URI, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the target Attribute name is not valid, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the target Attribute is scope, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI), and where specified type, is +equivalent held locally, and no matching registrations apply (see ), +then an error of type ResourceNotFound shall be raised. +
    • +
  • +The behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If an exclusive or redirect Context Source Registration matches against +the input data, the input data is forwarded. For each matching +registration: +
    • +
+
    +
  • +If the Replace Attribute operation is supported by the registration (see +clause +4.3.6), matching input data is forwarded to the Registration +endpoint. +
    • +
  • +If the Replace Attribute operation is not supported by the registration, +this shall result in an error of type Conflict in case the +complete Replace Attribute operation failed, or in a partial success if +some parts of it succeeded. +
    • +
+
+No further processing is required. +
+
    +
  • +For any inclusive Context +Source Registrations that exist and match against the remaining +input data, that input data is also forwarded in the case the Replace +Attribute operation is supported for remote processing to matching +endpoints. +
    • +
  • +Apply term expansion as mandated by clause +5.5.7, so that the fully qualified name (URI) associated to the +target Attribute is properly obtained. +
    • +
  • +If the target Entity does not contain the target Attribute: +
    • +
+
    +
  • +as a default instance in case no datasetId is present; +
    • +
  • +as an instance with the specified datasetId if present; +
    • +
+
+then this shall result in an error of type ResourceNotFound in +case the complete Replace Attribute operation failed, or in a partial +success if some parts of it succeeded. +
+
    +
  • +Completely replace the existing Attribute with the new Attribute content +provided. The system generated createdAt Temporal Property as +defined in clause +4.8 remains unchanged. +
    • +
+

5.6.19.5 Output +data

+

None.

+

5.6.20 Batch Entity +Merge

+

5.6.20.1 Description

+

This operation allows modification of a batch of NGSI-LD Entities +according to the JSON Merge Patch processing rules defined in IETF RFC +7396 [16] by adding +new attributes (Properties or Relationships) or modifying or deleting +existing attributes associated with an existing Entity.

+

5.6.20.2 Use case +diagram

+

A Context Producer can merge a +batch of Entities within an NGSI-LD system as shown in Figure +5.6.20.2‑1.

+
+ +
+
+Figure 5.6.20.2-1: Merge a batch of Entities use case +
+

5.6.20.3 Input +data

+
    +
  • +A JSON-LD Array containing one or more JSON-LD documents each one +representing an Entity as mandated by clause 5.2.4. +See clause +5.5.11.5 for information on behaviour when there is more than one +instance of the same entity in the input Array. +
    • +
+

5.6.20.4 Behaviour

+

Implementations shall exhibit the following behaviour:

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +Let S be an array which shall contain a list of Entity IDs, one for each +NGSI-LD Entity which was successfully processed. S shall be initialized +as the empty array. +
    • +
  • +Let E be an array which shall contain a list of BatchEntityError +as defined by clause +5.2.17, one for each NGSI-LD Entity which resulted in error. E shall +be initialized as the empty array. +
    • +
  • +For each Context Source Registration +CSR in the Context Registry: +
    +
      +
    • +Let IN be a copy of the original input array. +
      • +
    • +Remove from IN all Entities not matched by CSR and remove non-matching +Attributes from the remaining Entities. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching exclusive Context Source Registration, which is not +CSR itself. +
      • +
    • +Remove all Attributes from the remaining Entities in IN for which there +is a matching redirect Context Source Registration, unless CSR is +a redirect Context Source +Registration itself. +
      • +
    • +Remove all Entities without Attributes from IN. +
      • +
    • +If IN is empty, continue with the next Context Source Registration if there is +any. +
      • +
    • +If the Batch Entity Merge operation is supported by CSR: +
      +
        +
      • +Forward the Batch Entity Merge request with IN as input Array. +
        • +
      • +Merge the returned list of Entities successfully created with S. +
        • +
      • +Merge the returned list of Entities in Error with E. +
        • +
      • +
    • +Otherwise, if the Merge Entity operation (clause +5.6.17) is supported by CSR: +
      +
        +
      • +For each Entity EN in the input array: +
        +
          +
        • +Forward a Merge Entity request for Entity EN. +
          • +
        • +Merge any successful result(s) for Entity EN merged with S. +
          • +
        • +Merge any error result(s) for Entity EN merged with E. +
          • +
        • +
      • +
    • +Otherwise +
      +
        +
      • +In case CSR is an exclusive or +redirect Context Source +Registration, add an Error of type Conflict for each +Entity in IN to E. +
        • +
      • +
    • +
  • +For each of the NGSI-LD Entities included in the input Array execute the +behaviour defined by clause +5.6.17, but limited to a local operation, as follows: +
    • +
+
    +
  • +If the Entity was successfully merged (Attributes updated, appended or +deleted), then add the corresponding Entity ID to the S array. +
    • +
  • +If the Entity merge failed, then a new BatchEntityError shall be +added to E containing the failed Entity ID and the ProblemDetails +associated. +
    • +
+

5.6.20.5 Output +data

+
    +
  • +none (if all Entities already existed and are successfully merged); or +
    • +
  • +the list of Entities successfully merged (S Array), and the list of +Entities in error (E Array), if only some or none of the Entities have +been successfully merged. +
    • +
+

5.7 Context Information +Consumption

+

5.7.1 Retrieve +Entity

+

5.7.1.1 Description

+

This operation allows retrieving an NGSI-LD Entity.

+

5.7.1.2 Use case +diagram

+

A Context Consumer can retrieve a specific Entity from an +NGSI-LD system as shown in Figure +5.7.1.2‑1.

+
+ +
+
+Figure 5.7.1.2-1: Retrieve Entity use case +
+

5.7.1.3 Input data

+
    +
  • +Entity ID (URI) of the Entity to be retrieved (target Entity). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional). +
    • +
  • +List of Attribute (Properties or Relationships) names to +be retrieved (projection attributes) (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope” or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", "scope” or an +Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +A language filter as defined by clause +4.15 (optional). +
    • +
  • +An optional JSON-LD context. +
    • +
  • +In the case of a GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +An optional flag indicating whether to include additional Linked Entities corresponding to the +Relationships retrieved and how to format those Linked Entities. See clause +4.5.23 (optional). +
    • +
  • +A limit to the depth of Linked +Entities to search whilst traversing an Entity graph. See clause +4.5.23 (optional). +
    • +
  • +A list (one or more) of Linked Entity identifiers previously encountered +whilst traversing an Entity graph. See clause +4.5.23 (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation (optional). +
    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies which Attribute +instances are to be selected as defined by clause +4.5.5 (optional). +
    • +
+
+
+ +
+
+
+ +
+

5.7.1.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If geometryProperty parameter is present and the Accept Header is not +set to "application/geo+json", then an +error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval and the use of +Linked Entity retrieval is not +specified, or the projected attribute depth exceeds the Linked Entity retrieval depth, an error of +type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity held locally whose id (URI), and where +specified type, is equivalent, and no matching registrations apply, then +an error of type ResourceNotFound shall be raised. +
    • +
  • +The implementation shall retrieve any Attribute data held locally which +is associated with the Entity defined by the Entity ID. +
    • +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    • +
+
    +
  • +If the resource cannot be found, or the data has expired, a new +EntityMap shall be created. +
    • +
  • +If the data has not expired, the retrieved Entity Map shall be used to +determine which Context Source +Registrations match the Entity ID. +
    • +
+
    +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +For Context Source Registrations that +match the Entity ID and support the retrieveEntity operation (see +operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If an EntityMap is in use for this operation, and an EntityMap entry +linked to a Context Source +Registration is found, the location of the linked EntityMap shall +be passed as part of any forwarded request. +
    • +
  • +For any exclusive, redirect and +inclusive Context +SourceRegistrations, the +request is forwarded for remote retrieval by matching endpoints. and +remote Attribute data for the Entity is received. It is then merged +together according to the algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations the remote Attribute data received is added +to the payload only when an Attribute is not present in any of the +Attribute data received elsewhere. +
    • +
  • +If a EntityMap is in use for this operation, the EntityMap’s linked maps +are updated to hold the location of every EntityMap used by the Context Source Registrations +
    • +
+
    +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +For each Attribute found in the target Entity, when the datasetId +parameter is provided in the request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId +parameter,, i.e. keep only the Attribute instances whose datasetId is specified. The default +Attribute instance is matched, if "@none" +is specified. +
    • +
  • +If there is no Attribute instance whose datasetId +matches the value of the parameter, the Attribute shall not be +returned with the Entity. +
    • +
+
    +
  • +If the optional Attribute list is present and the NGSI-LD endpoint does +know about a matching Entity for the Entity ID, but this Entity does not +have any of the Attributes in the Attribute list, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If the Accept Header is set to "application/json" or "application/ld+json", return a JSON-LD object representing the +Entity as mandated by clause 5.2.4 +and containing only the Attributes requested (if present). +
    • +
  • +If the Accept Header is set to "application/geo+json", a GeoJSON +Feature object representing the entity as mandated by clause 5.2.29 +and containing only the Attributes requested (if present): +
    • +
+
    +
  • +If the Prefer Header is omitted or set to "body=ld+json" then the Feature object +will also contain an @context field. +
    • +
  • +If the Prefer Header is set to "body=json" the @context is set as a +Link Header and removed from the Feature object. +
    • +
+

5.7.1.5 Output +data

+

A JSON-LD object representing the target Entity as mandated by clause 5.2.4 or +a GeoJSON Feature as mandated by clause +5.2.29.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be +compacted according to the supplied @context.

+

If a language filter is specified and any of the returned Attributes +corresponds to a LanguageProperty, the LanguageProperty in +question shall be converted into a Property. The value of this +Property shall correspond to the value of the string or strings +from the matching key-value pair of the languageMap where the key +matches the language filter. A non-reified subproperty lang shall +be included in the response indicating the chosen language.

+

If no match can be made for a LanguageProperty then a single +language shall be chosen, up to the implementation.

+
+If inline Linked +Entity retrieval (see clause +4.5.23.2) is specified, and any of the returned Attributes +corresponds to an annotated Relationship, then unless a URI has +been previously encountered, an entity sub-Property shall be +included in the response holding the Linked +Entity data for each URI corresponding to that +Relationship's target object URI. If any of the returned +Attributes corresponds to an annotated ListRelationship, then an +entityList subproperty shall be included in the response holding +the ordered array of Linked +Entities corresponding to that ListRelationship's target +objectList URIs unless a URI has been previously encountered. +
+
+If flattened Linked +Entity retrieval (see clause +4.5.23.3) is specified, the response shall be an array of JSON-LD +objects representing the target entity itself and the targets of its +Relationships. If any of the returned Attributes corresponds to +an annotated Relationship, unless a target URI has been +previously encountered, the +data corresponding to each URI of the Relationship's target +object URIs is appended to the array. If any of the returned +Attributes corresponds to an annotated ListRelationship, then an +ordered array of additional Linked Entities is appended to the array +which hold the data corresponding to each of the URIs found within +ListRelationship's target objectList unless a URI has been +previously encountered. +
+
+Flattened Linked Entity retrieval +output changes to a GeoJSON FeatureCollection as mandated by clause +5.2.30 if the Accept Header is set to "application/geo+json". +
+
+If the location of a previously generated EntityMap was passed into the +request, or a flag to return an EntityMap was present in the request, +the location of the EntityMap used in the operation shall be returned in +a specific field in the response. +
+

5.7.2 Query Entities

+

5.7.2.1 Description

+

This operation allows querying an NGSI-LD system.

+

5.7.2.2 Use case +diagram

+

A Context Consumer can retrieve a set of entities which +matches a specific query from an NGSI-LD system as shown in Figure +5.7.2.2‑1.

+
+ +
+
+Figure 5.7.2.2-1: Query Entities use case +
+

5.7.2.3 Input data

+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type names (short hand string) and fully qualified type names (URI) +are allowed in the selector. +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope” or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list member names ("id", "type", "scope” or an Attribute name) to be removed +(projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +In the case of GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties +that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9. +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +An optional flag indicating whether to include additional Linked Entities corresponding to the +Relationships retrieved and how to format those Linked Entities. See clause +4.5.23 (optional). +
    • +
  • +A limit to the depth of Linked +Entities to search whilst traversing an Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A list (one or more) of Linked Entity identifiers previously encountered +whilst traversing an Entity Graph. See clause +4.5.23 (optional). +
    • +
  • +A flag indicating whether to return the location of the EntityMap used +within the operation. (optional) +
    • +
  • +The location of a resource holding an EntityMap of matching Entity +registrations (optional). +
    • +
  • +A datasetId parameter that specifies which Attribute +instances are to be selected as defined by clause +4.5.5 (optional). +
    • +
+

In the general case, it is not possible to retrieve a set of entities +by only specifying desired Entity identifiers, without further +specifying restrictions on the entities' types or attributes, either +explicitly, via selector of Entity types or of Attribute names, or +implicitly, within an NGSI-LD Query or GeoQuery. If the execution of the +operation is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided.

+

5.7.2.4 Behaviour

+
    +
  • +At least one of the following input data shall be provided: +
    • +
+
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause 5.5.13). +
+
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval, and the use of +Linked Entity retrieval is not +specified, or the projected attribute depth exceeds the Linked Entity retrieval depth, then an +error of type BadRequestData shall be raised +
    • +
  • +If the filter conditions specified by the query includes Linked Entity attributes, and the use of +Linked Entity retrieval is not +specified, or the Linked Entity +attribute query depth exceeds the Linked Entity retrieval depth, an error of +type BadRequestData shall be raised (too deep query). +
    • +
  • +If geometryProperty parameter is present and the Accept Header is not +set to "application/geo+json", then an +error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
    • +
  • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
    • +
  • +Otherwise, implementations shall run a query that shall return an Entity +Array containing all the Entities found locally, that meet +all of the following conditions (given the respective +parameter is provided): +
    • +
+
    +
  • +id is equal to any of the id(s) passed as a parameter; +
    • +
  • +the Entity Type names match the selector of Entity Types (expanded) that +is passed as a parameter; +
    • +
  • +Attribute matches any of the expanded attribute(s) in the list that is +passed as a parameter; +
    • +
  • +id matches the id pattern passed as a parameter; +
    • +
  • +the filter conditions specified by the query are met (as mandated by clause +4.9); +
    • +
  • +the geospatial restrictions imposed by the geoquery are met (as mandated +by clause +4.10); if there are multiple instances of the GeoProperty on +which the geoquery is based, it is sufficient if any of these instances +meets the geospatial restrictions; +
    • +
  • +if the Scope query is present, it shall match a present Entity Scope (as +mandated by clause +4.19, for an example see annex +C, clause +C.5.15); +
    • +
  • +if the Attribute list is present, in order for an Entity to match, it +shall contain at least one of the Attributes in the projection Attribute +list. +
    • +
+
    +
  • +If the ContextBroker implementation supports the use of EntityMaps then: +
    • +
+
    +
  • +If the location of a resource holding an EntityMap of matching Entity +registrations is present it shall be retrieved: +
    • +
+
    +
  • +If the resource cannot be found, or the data has expired, a new +EntityMap shall be created. +
    • +
  • +If the data has not expired, the retrieved EntityMap shall be used to +determine which Context Source +Registrations match the Entity ID. +
    • +
+
    +
  • +If a flag to return an EntityMap was present in the request, and no +EntityMap currently exists, then a new EntityMap shall be created. +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source +Registrations that match the query and support the “queryEntity” +operation (see operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +If a EntityMap is in use for this operation, and a EntityMap entry +linked to a Context Source +Registration is found, the location of the EntityMap shall be +passed as part of the forwarded request. +
    • +
  • +For any exclusive, redirect and +inclusive Context Source +Registrations, the request is forwarded for remote querying by +matching endpoints. The result of each remote query is an Entity Array. +The Entity Arrays are then merged together with the locally queried +result according to the algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations, the request is forwarded for remote +querying by matching endpoints. Data from the Entity Array received is +added to the payload only when an Attribute is not already present in +the merged Entity Arrays are received elsewhere. +
    • +
+
    +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +

  • If in the process of obtaining the query result it is necessary +to issue a Context Source discovery +operation, the same Context Source +filter input parameter (if present) shall be propagated.

    • +
  • +For each Attribute found in the target Entity, when datasetId +parameter is provided in the request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId +parameter,, i.e. keep only the Attribute instances whose datasetId is specified. The default +Attribute instance is matched, if "@none" +is specified. +
    • +
  • +If there is no Attribute instance whose datasetId +matches the value of the parameter, the Attribute shall not be +returned with the Entity. +
    • +
+
    +
  • +If the Accept Header is set to "application/json" or "application/ld+json", a JSON-LD +array is returned, representing the Entities as mandated by clause 5.2.4 +and containing only the Attributes requested (if present). +
    • +
  • +If the Accept Header is set to "application/geo+json", the response shall be a +GeoJSON FeatureCollection as mandated by clause +5.2.30, with each Feature within the FeatureCollection +containing only the Attributes requested (if present): +
    • +
+
    +
  • +If the Prefer Header is omitted or set to "body=ld+json" then the +FeatureCollection will also contain an @context field. +
    • +
  • +If the Prefer Header is set to "body=json" the @context is sent +as a Link Header and removed from the FeatureCollection object. +
    • +
+

5.7.2.5 Output +data

+

A JSON-LD array representing the matching entities as defined by clause 5.2.4 or +in the case of GeoJSON requests a FeatureCollection as mandated +by clause +5.2.30. For each matching Entity, only the Attributes specified by +the Attribute list parameter shall be included. If such parameter is not +present, then all Attributes shall be included.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

If any of the returned Attributes corresponds to a VocabProperty, the returned value shall be +compacted according to the supplied @context.

+

If a language filter is specified and any of the returned Attributes +corresponds to a LanguageProperty, the LanguageProperty in +question shall be converted into a Property. The value of this +Property shall correspond to the value of the string or strings +from matching key-value pair of the languageMap where the key +matches the language filter. A non-reified subproperty lang shall be included in the +response indicating the chosen language.

+

If no match can be made for a LanguageProperty, then the +default identified by the JSON-LD "@none" shall be +chosen if present, otherwise the choice of a single language is up to +the implementation.

+
+If inline Linked +Entity retrieval (see clause +4.5.23.2) is specified, and any of the returned Attributes +corresponds to an annotated Relationship, then unless a URI has +been previously encountered, an entity subproperty shall also be +included in the response holding the data for each URI corresponding to +that Relationship's target object URIs. If any of the +returned Attributes corresponds to an annotated ListRelationship, +then an entityList subproperty shall also be included in the +response holding the ordered data corresponding to that +ListRelationship's target objectList URIs, unless a URI +has been previously encountered. +
+
+If flattened Linked +Entity retrieval (see clause +4.5.23.3) is specified, the response shall be an array of JSON-LD +objects representing the matching entities and the targets of their +Relationships. If any of the returned Attributes corresponds to +an annotated Relationship, unless a URI has been previously +encountered, then data for each URI corresponding to the +Relationship's target object URIs is appended to the +array. If any of the returned Attributes corresponds to an annotated +ListRelationship, then an array of additional Linked Entities is appended to the array +which hold the data corresponding to each of the URIs found within +ListRelationship's target objectList unless a URI has been +previously encountered. +
+
+If the location of a previously generated EntityMap was passed into the +request, or a flag to return an EntityMap was present in the request, +the location of the EntityMap used in the operation shall be returned in +a specific field in the response. +
+

5.7.3 Retrieve Temporal +Evolution of an Entity

+

5.7.3.1 Description

+

This operation allows retrieving the Temporal +Evolution of an Entity.

+

5.7.3.2 Use case +diagram

+

A Context Consumer can retrieve +the Temporal Evolution of an +Entity (in the form of a temporal representation) from an NGSI-LD +system as shown in Figure +5.7.3.2‑1.

+
+ +
+
+Figure 5.7.3.2-1: Retrieve Temporal Evolution of an Entity use case +
+

5.7.3.3 Input data

+
    +
  • +Entity ID (URI) of the target Temporal Evolutionof an +Entity to be retrieved. +
    • +
  • +List of Attribute (Properties or Relationships) names to be retrieved +(projection attributes) (optional). +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope” or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", "scope” or an +Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An NGSI-LD temporal query as mandated by clause +4.11 (optional). +
    • +
  • +A parameter (lastN) conveying that only the last N instances (per +Attribute) within the concerned temporal interval shall be retrieved +(optional). +
    • +
  • +An optional JSON-LD context. +
    • +
  • +A datasetId parameter that specifies which Attribute +instances are to be selected as defined by clause +4.5.5 (optional). +
    • +
+

5.7.3.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If projection attributes are present and indicate the use of Linked Entity retrieval, an error of type +BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target Entity, because +there is no existing Entity whose id (URI) is equivalent held locally, +and no matching registrations apply, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +The lastN parameter refers to a number, n, of Attribute +instances which shall correspond to the last n timestamps (in +descending ordering) of the temporal property (by default +observedAt) within the concerned temporal interval. +
    • +
  • +Let S be the Temporal Evolution of +the Entity as mandated by clause +5.2.20 with the specified Entity ID as it is available locally. S is +empty in case no Temporal Evolution of +the Entity is available locally. +
    • +
  • +From S, select only those Attribute instances (corresponding to the +Attributes specified by the query or all if none are specified) match +the temporal restrictions imposed by the temporal query (as mandated by +clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S1 be this new subset. +
    • +
  • +For Context Source Registrations that +match the Entity ID and support the retrieveTemporal operation (see +operations and operation groups in clause +4.20), implementations shall do the following +
    • +
+
    +
  • +For any exclusive, redirect and +inclusive Context +Source, the request is forwarded for remote retrieval by matching +endpoints. and remote Attribute data for the Entity is received. The +result is then merged together with S1 according to the algorithm +defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations the remote Attribute data received is added +to S1 only when the Attribute instance, whose value of the +timeproperty, which is used for the temporal query +(observedAt as default), is not present in any of the Attribute +instances received from elsewhere. +
    • +
+
    +
  • +For the set of Attribute Instances +that are in S1, when datasetId parameter is provided in the request: +
    • +
+
    +
  • +Filter the Attribute instances based on the datasetId +parameter,, i.e. keep only the Attribute instances whose datasetId is specified. The default +Attribute instance is matched, if "@none" +is specified. +
    • +
  • +If there is no Attribute instance whose datasetId +matches the value of the parameter, remove the complete Attribute +from S1. +
    • +
+
    +
  • +From the set of Attribute Instances +that are in S1, include in their temporal representation only the +Attribute instances (up to lastN) corresponding to the query's +projection Attributes, or aggregated values of Attribute instances (if +aggregated temporal representation is requested). +
    +
    +In the general case, it is not possible to retrieve a set of entities by +only specifying desired Entity identifiers, without further specifying +restrictions on the entities' types or attributes, either explicitly, +via selector of Entity types or of Attribute names, or implicitly, +within an NGSI-LD Query or GeoQuery. If the execution of the operation +is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided. +
    • +
+

5.7.3.5 Output +data

+

A JSON-LD object representing the Temporal Evolution of +the target Entity as mandated by clause +5.2.20.

+

If a restrictive list of Entity member names is present, every Entity +within the payload body is reduced down to only contain the defined +Entity members.

+

If an exclusionary list of Entity member names is present, the +defined Entity members listed are removed from each Entity within the +payload.

+

5.7.4 Query Temporal +Evolution of Entities

+

5.7.4.1 Description

+

This operation allows querying the Temporal +Evolution of Entities present in an NGSI-LD +system. It is similar to the operation defined by clause +5.7.2 (Query Entities) with the addition of a temporal query.

+

5.7.4.2 Use case +diagram

+

A Context Consumer can retrieve +the Temporal Evolution of a set of Entities which matches a specific +query from an NGSI-LD system as shown in Figure +5.7.4.2‑1.

+
+ +
+
+Figure 5.7.4.2-1: Query Temporal Evolution of Entities use case +
+

5.7.4.3 Input data

+
    +
  • +An NGSI-LD temporal query as mandated by clause +4.11. +
    • +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17 (optional).
    +Both type name (short hand string) and fully qualified type name (URI) +are allowed. +
    • +
  • +A restrictive list of Entity member names ("id", "type", "scope” or an +Attribute name) to be retrieved (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +An exclusionary list of Entity member names ("id", "type", "scope” or an +Attribute name) to be removed (projection attributes as defined by clause +4.21) (optional). +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names of which at least one shall +exist in order for an Entity to be selected, and also used as query +projection attributes (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships) as +mandated by clause +4.10 (optional). +
    • +
  • +A NGSI-LD Scope query (to filter out Entities based on their Scope) as +mandated by clause +4.19 (optional). +
    • +
  • +An NGSI-LD query (called context source filter, to filter out Context Sources by the values of properties +that describe them) as per clause +4.9 (optional). +
    • +
  • +A limit to the number of Entities to be retrieved. See clause +5.5.9. +
    • +
  • +A parameter (lastN) conveying that only the last N instances (per +Attribute) within the concerned temporal interval shall be retrieved +(optional). +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
  • +A list (one or more) of Attribute names whose values shall be expanded +to URIs prior to executing a query (optional). +
    • +
  • +A datasetId parameter that specifies which Attribute instances are to be +selected as defined by clause +4.5.5 (optional). +
    +
    +In the general case, it is not possible to retrieve a set of entities by +only specifying desired Entity identifiers, without further specifying +restrictions on the entities' types or attributes, either explicitly, +via selector of Entity types or of Attribute names, or implicitly, +within an NGSI-LD query or geoquery. If the execution of the operation +is limited to the local scope (see clause +5.5.13), no further restrictions have to be provided. +
    • +
+

5.7.4.4 Behaviour

+
    +
  • +If a temporal query is not provided then an error of type +BadRequestData shall be raised. +
    • +
  • +At least one of the following input data shall be provided: +
    • +
+
+
+a) selector of Entity Types; +
+
+b) list of Attribute names, including at least one non-system Attribute; +
+
+c) NGSI-LD Query, including at least one non-system Attribute; +
+
+d) NGSI-LD GeoQuery; +
+
+e) local scope (see clause 5.5.13). +
+
+
+If none of the above is provided, then an error of type +BadRequestData shall be raised (too wide query). +
+
    +
  • +If projection attributes or filter conditions indicate the use of Linked Entity retrieval, an error of type +BadRequestData shall be raised. +
    • +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or context source filter are not syntactically +valid (as per the referred clauses 4.9 +and 4.10) +an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be observed +mandated by clause +5.5.7. +
    • +
  • +If a list of Attribute names whose values shall be expanded to URIs has +been supplied, JSON-LD type coercion shall be performed as mandated by +clause +5.5.7. +
    • +
  • +The lastN parameter refers to a number, n, of Attribute +instances which shall correspond to the last n timestamps (in +descending ordering) of the temporal property (by default +observedAt) within the concerned temporal interval. +
    • +
  • +Otherwise, implementations shall run a query that shall return the +Temporal Evolution of the matching Entities (all Entities stored +locally, in case only a local scope is specified); the logical steps to +select the final result set of Entities, and the Attribute instances +included as part of their temporal representation, are enumerated as +follows: +
    • +
+
    +
  • +Let S be the set of selected Entities i.e. the query result set. +
    • +
  • +If id(s) is provided, keep in S only those Entities whose id is +equivalent to any of the id(s) passed as a parameter. +
    • +
  • +If an id pattern is provided, keep in S only those Entities whose id +matches the id pattern. +
    • +
  • +If a selector of Entity Types is provided, keep in S only those Entities +whose Entity Type names match the selector of Entity Types. +
    • +
  • +From S, select only those Entities any of whose Attribute instances +(corresponding to the Attributes specified by the query or all if none +are specified) match the temporal restrictions imposed by the temporal +query (as mandated by clause +4.11); i.e. if the time series, for all the concerned Attributes of +an Entity, does not include data corresponding to the temporal query +interval, then such Entity shall be removed from S, thus it shall not +appear in the final result set. Let S1 be this new subset. +
    • +
  • +If a values filter query is provided, from S1, select those Entities +whose Attribute instances (during the interval defined by the temporal +query) meet the matching conditions specified by the query (as mandated +by clause +4.9); i.e. the values filter query shall be checked against all the +Attribute instances resulting from the initial filtering performed by +the temporal query. Let S2 be this new subset. +
    • +
  • +If no values filter query is provided, then S2 is equal to S1. +
    • +
  • +If geoquery is present, from S2, select those Entities whose +GeoProperty instances meet the geospatial restrictions imposed by +the geoquery (as mandated by clause +4.10); those geospatial restrictions shall be checked against the +GeoProperty instances that are within the interval defined by the +temporal query. Let S3 be this new subset. +
    • +
  • +If no geoquery is provided, then S3 is equal to S2. +
    • +
  • +If the Scope query is present, from S3, select those Entities whose +Entity Scope instances match the Scope query (as mandated by clause +4.19, for an example see annex +C, clause +C.5.16). Let S4 be the new subset. +
    • +
  • +If no Scope query is provided, then S4 is equal to S3. +
    +
    + +
    • +
+
    +
  • +Unless local scope is specified (see clause +5.5.13), for Context Source +Registrations that match the query and support the +“queryTemporal” operation (see operations and operation groups in clause +4.20), implementations shall do the following: +
    • +
+
    +
  • +For any exclusive, redirect and +inclusive Context Source +Registrations that match against the query, the request is +forwarded for remote querying by matching endpoints. The result of each +remote query is an Entity Array. The returned result is then merged into +S4 according to the algorithm defined in clause +4.5.5. +
    • +
  • +For any auxiliary Context +Source Registrations that match against the query, the request is +forwarded for remote querying by matching endpoints. Data from the +Entity Array received is merged only into S4 when an Attribute instance, +whose value of the timeproperty used for the temporal query, is not +already present in S4. +
    • +
+
    +
  • +If a datasetIdparameter is provided, from S4, for all +Entities, filter the Attribute instances based on the datasetIds +specified in the parameter, i.e. keep only the Attribute +instances whose datasetId is specified. The default +Attribute instance is matched, if "@none" +is specified. Remove all Attributes without remaining Attribute +instances. Let S5 be this new subset. +
    • +
  • +If no datasetId is provided then S5 +equals to S4. +
    • +
  • +From the set of Entities that are in S4, include in their temporal +representation only the Attribute instances (up to lastN) +corresponding to the query's projection Attributes, or aggregated values +of Attribute instances (if aggregated temporal representation is +requested), and which meet the temporal, query and geoquery +restrictions. +
    +
    +If an aggregated temporal representation is requested and any of the +requested Attributes is not eligible for at least one of the aggregation +methods specified in the request parameters, then an error of type +InvalidRequest shall be raised. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
  • +If in the process of obtaining the query result it is necessary to issue +a Context Source discovery operation, +the same Context Source filter input +parameter (if present) shall be propagated. +
    • +
+

5.7.4.5 Output +Data

+

A JSON-LD array representing the matching entities as defined by clause +5.2.21 and selected according to the behaviour described by clause +5.7.4.4.

+

5.7.5 Retrieve Available Entity +Types

+

5.7.5.1 Description

+

This operation allows retrieving a list of NGSI-LD entity types for +which entity instances exist within the NGSI-LD system.

+

5.7.5.2 Use case +diagram

+

A Context Consumer can retrieve a list of NGSI-LD entity types +from the system as shown in Figure +5.7.5.2‑1.

+
+ +
+
+Figure 5.7.5.2-1: Retrieve Available Entity Types use case +
+

5.7.5.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.5.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the list of entity types, as +mandated by clause +5.2.24, for which entity instances exist within the NGSI-LD system. +See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.5.5 Output +data

+

A JSON-LD object representing the list of available entity types, as +mandated by clause +5.2.24.

+

5.7.6 Retrieve Details +of Available Entity Types

+

5.7.6.1 Description

+

This operation allows retrieving a list with a detailed +representation of NGSI-LD entity types for which entity instances exist +within the NGSI-LD system. The detailed representation includes the type +name (as short name if available in the provided @context) and +the attribute names that existing instances of this entity type +have.

+

5.7.6.2 Use case +diagram

+

A Context Consumer can retrieve a list with a detailed +representation of NGSI-LD entity types from the system as shown in Figure +5.7.6.2‑1.

+
+ +
+
+Figure 5.7.6.2-1: Retrieve Details of Available Entity Types use case +
+

5.7.6.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.6.4 Behaviour

+
    +
  • +Return a list of JSON-LD objects representing the details of available +entity types as mandated by clause +5.2.25 for which entity instances exist within the NGSI-LD system. +See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.6.5 Output +data

+

A list of JSON-LD objects representing the details of available +entity types as mandated by clause +5.2.25.

+

5.7.7 Retrieve +Available Entity Type Information

+

5.7.7.1 Description

+

This operation allows retrieving detailed entity type information +about a specified NGSI-LD entity type for which entity instances exist +within the NGSI-LD system. The detailed representation includes the type +name (as short name if available in the provided @context), the +count of available entity instances and details about attributes that +existing instances of this entity type have, including their name (as +short name if available in the provided @context) and a list of +types the attribute can have (e.g. Property, Relationship +or GeoProperty).

+

5.7.7.2 Use case +diagram

+

A Context Consumer can retrieve a detailed representation of a +specified NGSI-LD entity type from the system as shown in Figure +5.7.7.2‑1.

+
+ +
+
+Figure 5.7.7.2-1: Retrieve Available Entity Type Information use case +
+

5.7.7.3 Input data

+
    +
  • +Entity type name for which detailed information is to be retrieved. +
    • +
  • +An optional JSON-LD context. +
    • +
+

5.7.7.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the details of the specified entity +type as mandated by clause +5.2.26, for which instances exist within the NGSI-LD system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.7.5 Output +data

+

A JSON-LD object representing the details of the specified entity +type as mandated by clause +5.2.26.

+

5.7.8 Retrieve Available +Attributes

+

5.7.8.1 Description

+

This operation allows retrieving a list of NGSI-LD attributes that +belong to entity instances existing within the NGSI-LD system.

+

5.7.8.2 Use case +diagram

+

A Context Consumer can retrieve a list of NGSI-LD attributes +from the system as shown in Figure +5.7.8.2‑1.

+
+ +
+
+Figure 5.7.8.2-1: Retrieve Available Attributes use case +
+

5.7.8.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.8.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the list of attributes as mandated +by clause +5.2.27 that belong to entity instances existing within the NGSI-LD +system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.8.5 Output +data

+

A JSON-LD object representing the list of available attributes as +mandated by clause +5.2.27.

+

5.7.9 Retrieve Details +of Available Attributes

+

5.7.9.1 Description

+

This operation allows retrieving a list with a detailed +representation of NGSI-LD attributes that belong to entity instances +existing within the NGSI-LD system. The detailed representation includes +the attribute name (as short name if available in the provided +@context) and the type names for which entity instances exist +that have the respective attribute.

+

5.7.9.2 Use case +diagram

+

A context consumer can retrieve a list with a detailed representation +of NGSI-LD attributes from the system as shown in Figure +5.7.9.2‑1.

+
+ +
+
+Figure 5.7.9.2-1: Retrieve Details of Available Attributes use case +
+

5.7.9.3 Input data

+
    +
  • +An optional JSON-LD context. +
    • +
+

5.7.9.4 Behaviour

+
    +
  • +Return a list of JSON-LD objects representing the details of available +attributes as mandated by clause +5.2.28 (restricted to the elements id, type, +attributeName and typeNames) that belong to entity +instances existing within the NGSI-LD system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.9.5 Output +data

+

A list of JSON-LD objects representing the details of available +attributes as mandated by clause +5.2.28 (restricted to the elements id, type, attributeName and +typeNames).

+

5.7.10 Retrieve +Available Attribute Information

+

5.7.10.1 Description

+

This operation allows retrieving detailed attribute information about +a specified NGSI-LD attribute that belongs to entity instances existing +within the NGSI-LD system. The detailed representation includes the +attribute name (as short name if available in the provided +@context) and the type names for which entity instances exist +that have the respective attribute, a count of available attribute +instances and a list of types the attribute can have (e.g. +Property, Relationship or GeoProperty).

+

5.7.10.2 Use case +diagram

+

A context consumer can retrieve a list with a detailed representation +of NGSI-LD attributes from the system as shown in Figure +5.7.10.2‑1.

+
+ +
+
+Figure 5.7.10.2-1: Retrieve Available Attribute Information use case +
+

5.7.10.3 Input +data

+
    +
  • +Name of the attribute for which detailed information is to be retrieved. +
    • +
  • +An optional JSON-LD context. +
    • +
+

5.7.10.4 Behaviour

+
    +
  • +Return a JSON-LD object representing the details of available attributes +as mandated by clause +5.2.28 that belong to entity instances existing within the NGSI-LD +system. See clause +5.7.11 for architecture-related implementation aspects. +
    • +
+

5.7.10.5 Output +data

+

A JSON-LD object representing the details of available attributes as +mandated by clause +5.2.28.

+

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

+

Retrieving information about available types or attributes can be an +expensive operation depending on the scale and architectural design +decisions of the NGSI-LD system. This is in particular the case for +retrieving the information about all available entity types and +attributes related to all entity information available in an NGSI-LD +system. Especially in the case of distributed architecture (clause +4.3.3) and federated architecture (clause +4.3.4) checking all entities can be so expensive that it can become +practically infeasible.

+

Therefore, implementations may only take into account only +information that is available or can be derived from a local datastore +and the Context Registry, when +implementing the retrieval of available entity types and attributes, as +described in clauses 5.7.5, +5.7.6, +5.7.7, +5.7.8, +5.7.9 +and 5.7.10. +Context registrations do not always reflect which entity instances are +actually available from a Context +Source at a particular point in time, but only which entity +instances are possibly available from a Context Source, thus in this case the +information about available entity types and attributes is to be +interpreted as "possibly available". Also, context registrations can +have different granularities, i.e. they possibly only contain entity +type or attribute information, and thus the provided information about +available entity types and attributes is possibly incomplete as a +result. In particular the attributeNames in the EntityType +data structure (clause +5.2.25), the attributeDetails in the EntityTypeInfo +data structure (clause +5.2.26), and the attributeTypes and typeNames in the +Attribute data structure (clause +5.2.27) may be provided as empty arrays if the information is not +included in the respective context registration. Implementations may +also provide estimates for the entity count or attribute count instead +of the accurate count.

+

As an alternative to relying on local information only, the request +can be forwarded to all Context +Sources which support the respective operation according to the +Context Source Registration +describing them. In this case the returned lists are merged with the +local list of entity types before returning them. This approach is more +expensive but leads to a more accurate result.

+

5.8 Context Information +Subscription

+

5.8.1 Create +Subscription

+

5.8.1.1 Description

+

This operation allows creating a new subscription.

+

5.8.1.2 Use case +diagram

+

A Context Subscriber can create a subscription to receive +context updates within an NGSI-LD system as shown in Figure +5.8.1.2‑1.

+
+ +
+
+Figure 5.8.1.2-1: Create subscription use case +
+

5.8.1.3 Input data

+
    +
  • +A data structure (represented in JSON-LD) conforming to the +Subscription data type as mandated by clause +5.2.12. +
    • +
+

5.8.1.4 Behaviour

+
    +
  • +If the data types, cardinalities and restrictions expressed by clause +5.2.12 are not met, then an error of type BadRequestData +shall be raised. +
    • +
  • +If the NGSI-LD endpoint already knows about this Subscription, as there +is an existing Subscription whose id (URI) is equivalent, an error of +type AlreadyExists shall be raised. +
    • +
  • +If the subscription document does not include a Subscription identifier, +a new identifier (URI) shall be automatically generated by the +implementation. +
    • +
  • +Then, implementations shall add a new Subscription. The parameters of +the created Subscription shall be configured as follows: +
    • +
+
    +
  • +The Subscription expiration date shall be equal to the value of the +expiresAt member. If the expiration timestamp provided represents +a moment before the current date and time, then an error of type +BadRequestData shall be raised. If there is no expiresAt +member the Subscription shall be considered as perpetual. +
    • +
  • +If the value of the isActive field is not included or is +true then the initial status of the Subscription shall be set to +"active". +
    • +
  • +If the value of the isActive field is false, then the +initial status of the Subscription shall be set to "paused". +
    • +
  • +If present, the subscribed entities shall be those matching the +conditions expressed under the EntitySelector, as defined in clause +5.2.33. +
    • +
  • +Watched Attributes shall be those Attributes (subject to clause +5.5.7 Term to URI expansion) pertaining to the subscribed entities +(if present) and conveyed through the watchedAttributes member. +Watched Attributes are those that trigger a new notification when they +are changed. A non-present watchedAttributes member means that +all Attributes shall be watched. If no subscribed entities have been +specified, all entities with attributes matching at least one member of +watchedAttributes are subscribed to. +
    • +
  • +The @context to be used for sending Notifications related to this +Subscription shall be the one specified in the jsonldContext +field. If not present, the jsonldContext field shall be +initialized with the @context applicable for the Subscription (if +@context is also not present in the Subscription, see clause +5.5.5). When the remote JSON-LD @context referenced by the +jsonldContext field is not available implementations shall raise +an error of type LdContextNotAvailable. If the remote JSON-LD +@context referenced by the jsonldContext field is invalid, +implementations shall raise an error of type BadRequestData. +
    • +
  • +Based on the content of the Subscription, a Context Source Registration Subscription +shall be created (clause +5.11.2). The mapping of the id of the Subscription to the +returned subscriptionId of the Context Source Registration Subscription +shall be stored to enable updating or deleting the Context Source Registration Subscription in +case of changes to the Subscription. +
    • +
+
    +
  • +If the subscription defines a timeInterval member, a Notification +shall be sent periodically, when the time interval (in seconds) +specified in such value field is reached, regardless of Attribute +changes. +
    • +
  • +If timeInterval is not defined, whenever there is a change in the +watched Attribute nodes (Properties or Relationships) of the concerned +Entities, implementations shall post a new Notification as per the rules +defined by clause +5.8.6. +
    • +
  • +Each time a Context Source +Notification with the subscriptionId of the previously created +Context Source Registration +Subscription is received, implementations shall do the following: +
    +
      +
    • +For any exclusive, redirect and +inclusive Context Source +Registration received as part of the notification, implementation +shall do the following depending on the triggerReason: +
      +
        +
      • +If the triggerReason is "newlyMatching" and the Context Source Registration indicates +support for the Create Subscription operation, a copy of the original +Subscription shall be reduced to what is matched by the registration +information and forwarded to the Context Source as a new Subscription where +the notification endpoint is set to that of the local Broker. The +mapping of the received subscriptionId with the own Subscription +identifier is stored to enable forwarding received notifications to the +original subscriber. In addition, a mapping of the id of the Context Source Registration to the received +subscriptionId is stored, to enable updating or deleting the +subscription in case of changes. +
        • +
      • +If the triggerReason is "updated" +and the Context Source Registration +indicates support for the Update Subscription operation, an update of +the original Subscription, reduced to what is matched by the +registration information, shall be forwarded to the Context Source with the +subscriptionId related to the Context +Source Registration. As an optimization, an implementation may +keep the originally forwarded Context Source +Registration and compare with the new one to only forward the +update, if there was a relevant change. +
        • +
      • +If the triggerReason is "noLongerMatching" and the Context Source Registration indicates +support for the delete Subscription operation, a delete Subscription +shall be forwarded to the Context +Source with the subscriptionId related to the Context Source Registration. +
        • +
      • +
    • +
  • +Implementations shall ensure that, when the Subscription expiration date +is due, the status of the Subscription changes automatically to "expired", so +that notifications will no longer be sent. +
    • +
+

5.8.1.5 Output +data

+
    +
  • +One subscription identifier (id) of type string, representing a URI. +Implementations shall ensure that subscription identifiers are unique +within an NGSI-LD system. +
    • +
+

5.8.2 Update +Subscription

+

5.8.2.1 Description

+

This operation allows updating an existing subscription.

+

5.8.2.2 Use case +diagram

+

A Context Subscriber can update an existing subscription +within an NGSI-LD system as shown in Figure +5.8.2.2‑1.

+
+ +
+
+Figure 5.8.2.2-1: Update subscription use case +
+

5.8.2.3 Input data

+
    +
  • +Subscription identifier (URI), the target subscription. +
    • +
  • +A JSON-LD document representing a Subscription Fragment. +
    • +
+

5.8.2.4 Behaviour

+
    +
  • +If the Subscription id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD System does not know about the target Subscription, +because there is no existing Subscription whose id (URI) is equivalent, +an error of type ResourceNotFound shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.12 are not met by the Subscription Fragment, then an +error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +If the jsonldContext field is present and the referenced JSON-LD +@context is not available, implementations shall raise an error +of type LdContextNotAvailable. If the referenced JSON-LD +@context is invalid, implementations shall raise an error of type +BadRequestData. +
    • +
  • +Then, implementations shall modify the target Subscription as mandated +by clause +5.5.8. +
    • +
  • +Finally, the following extra behaviour shall be observed when updating +Subscriptions: +
    • +
+
    +
  • +If isActive is equal to true and expiresAt is not +present, then status shall be updated to "active", if and only if, the previous value of +status was different than "expired". +
    • +
  • +If isActive is equal to true and expiresAt +corresponds to a DateTime in the future, then status shall +be updated to "active". +
    • +
  • +If isActive is equal to false and expiresAt is not +present, then status shall be updated to "paused", if and only if, the previous value of +status was different than "expired". +
    • +
  • +If only expiresAt is included and refers to a DateTime in +the future, then status shall be updated to "active", if and only if the previous value of +status was "expired". +
    • +
  • +If expiresAt is included but referring to a DateTime in +the past, then a BadRequestData error shall be raised, regardless +the value of isActive. +
    • +
  • +Based on the mapping of the Subscription to its respective Context Source Registration Subscription +(see clause +5.8.1.4), that Context Source +Registration Subscription shall be updated (clause +5.11.3). +
    • +
+

5.8.2.5 Output +data

+

None.

+

5.8.3 Retrieve +Subscription

+

5.8.3.1 Description

+

This operation allows retrieving an existing subscription.

+

5.8.3.2 Use case +diagram

+

A Context Subscriber can retrieve a specific subscription from +an NGSI-LD system as shown in Figure +5.8.3.2‑1.

+
+ +
+
+Figure 5.8.3.2-1: Retrieve subscription use case +
+

5.8.3.3 Input data

+
    +
  • +Id (URI) of the subscription to be retrieved (target subscription). +
    • +
+

5.8.3.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the identifier provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall query the subscriptions and obtain the +subscription data to be returned to the caller. +
    • +
+

5.8.3.5 Output +data

+

A JSON-LD object representing the subscription details as mandated by +clause +5.2.12.

+

5.8.4 Query +Subscriptions

+

5.8.4.1 Description

+

This operation allows querying existing Subscriptions.

+

5.8.4.2 Use case +diagram

+

A Context Consumer can query the +existent Subscriptions from an NGSI-LD system as shown in Figure +5.8.4.2‑1.

+
+ +
+
+Figure 5.8.4.2-1: Query subscriptions use case +
+

5.8.4.3 Input data

+
    +
  • +A limit to the number of subscriptions to be retrieved. See clause +5.5.9. +
    • +
+

5.8.4.4 Behaviour

+
    +
  • +The NGSI-LD system shall list all the existing subscriptions up to the +limit specified as input data. If no limit is specified the number of +subscriptions retrieved may depend on the implementation. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.8.4.5 Output +data

+

A list (represented as a JSON array) of JSON-LD objects each one +representing subscription details as mandated by clause +5.2.12.

+

5.8.5 Delete +Subscription

+

5.8.5.1 Description

+

This operation allows deleting an existing subscription.

+

5.8.5.2 Use case +diagram

+

A Context Subscriber can delete a subscription within an +NGSI-LD system as shown in Figure +5.8.5.2‑1.

+
+ +
+
+Figure 5.8.5.2-1: Delete subscription use case +
+

5.8.5.3 Input data

+
    +
  • +A subscription identifier (URI). +
    • +
+

5.8.5.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the subscription id provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall delete the Subscription and no longer +perform notifications concerning such Subscription. +
    • +
  • +Using the mapping of the own Subscription identifier to each of the +subscriptionId of a subscription to a Context Source, a delete Subscription shall +be forwarded to each such Context +Source, if the delete Subscription operation is supported as +indicated in the corresponding Context +Source Registration. +
    • +
+
    +
  • +Based on the mapping of the Subscription to its respective Context Source Registration Subscription +(see clause +5.8.1.4), that Context Source +Registration Subscription shall be deleted (clause +5.11.6). +
    • +
+

5.8.5.5 Output +data

+

None.

+

5.8.6 Notification behaviour

+

A notification is a message that allows a subscriber to be aware of +the changes in subscribed Entities. Implementations shall exhibit the +following behaviour:

+
    +
  • +Notifications shall only be sent if and only if the status of the +corresponding subscription (subscription.status) is "active", i.e. +not "paused" nor "expired". +
    • +
  • +If a Subscription defines a timeInterval member, a Notification +shall be sent periodically, when the time interval (in seconds) +specified in such value field is reached, regardless of Attribute +changes. The notification message shall include all the subscribed +Entities that match the query, geoquery and Scope query conditions. If +none of query, geoquery and Scope query are defined, then all subscribed +Entities shall be included. For each entity in the notification, only +the Attribute instances are to be included that match the +datasetId member in Subscription. If there are no matching +Entities, no Notification is sent. +
    • +
  • +If a Subscription does not define a timeInterval term, the +notification shall be sent whenever there is a change in the watched +Attributes. An Attribute is considered to change when any of the members +(including children) in its corresponding JSON-LD node is updated with a +value different than the existing one. The notification message shall +include all the subscribed Entities that changed and that match (as +mandated by clauses 4.9 +and 4.10) +the query and geoquery conditions. If query or geoquery are not defined +then all subscribed Entities that changed shall be included. If, for an +Entity, there are multiple instances of the GeoProperty on which +the geoquery is based, it is sufficient if any of these instances meets +the geospatial restrictions. For each entity in the notification, only +the Attribute instances are to be included that match the +datasetId member in Subscription. Finally, if a Context Source filter is defined, then only +the subscribed Entities whose origin Context +Source matches the referred filter shall be included. +
    • +
  • +If a Notification with a subscriptionId is received that has a +mapping to a local Subscription identifier, the Notification shall be +forwarded to the Notification endpoint specified in the local +Subscription, using this local Subscription identifier instead of the +subscriptionId received. +
    • +
  • +A Notification shall be sent as follows: +
    • +
+
    +
  • +The structure of the notification message shall be as mandated by clause +5.3.1. +
    • +
  • +The @context to be used is the one specified in the jsonldContext +field of the corresponding Subscription. +
    • +
  • +The Attributes included (Properties or Relationships) +shall be those specified by the notification.attributes member in +the Subscription data type (clause +5.2.12). Term to URI expansion shall be observed (clause +5.5.7). The absence of the notification.attributes member of +a Subscription means that all Attributes shall be included. If the +notification was triggered by the deletion of an Entity and the +notification.showChanges member is not set to true, only +the deletedAt system property shall be provided. In case +notification.sysAttrs is set to true, also +createdAt and modifiedAt shall be provided. +
    • +
  • +If an Attribute has been deleted, only the name of the attribute as key +and the URI "urn:ngsi-ld:null" as value +shall be provided, unless more information is required. The latter is +the case, if: +
    • +
+
    +
  • +a datasetId needs to be provided; +
    • +
  • +the notification.sysAttrs is set to true and thus the +system generated sub-attributes (see clause +4.8) have to be provided; +
    • +
  • +notification.showChanges is set to true and thus a +previous value or object has to be provided. +
    • +
+
+ In all such cases, a JSON object with all the required information is +provided, where the value or the object is set to the URI +"urn:ngsi-ld:null" respectively or, in +case of a LanguageProperty, the languageMap is set to +{"@none": "urn:ngsi-ld:null"}. +
+
    +
  • +If the +notification.formatmember value isset, the representation of the +entities changes: +
    • +
+
    +
  • +If the notification.format is set to "concise" then a concise +representation of the entities shall be provided as defined by clause +4.5.1. +
    • +
  • +If the notification.format is set to "simplified" (or "keyValues" as a synonym), then a simplified +representation of the entities (as mandated by clause +4.5.4) shall be provided. +
    • +
  • +Otherwise the normalized format as defined by clause +4.5.1 shall be used. +
    • +
+
    +
  • +If the +notification.pickmember value is set, every +Entity within the payload body is reduced down to only contain the +defined entity members listed. +
    • +
  • +If the +notification.omitmember value is set, the +defined entity members listed are removed from each Entity within the +payload. +
    • +
  • +If the +notification.joinmember value is set then Linked Entityretrieval(as mandated by clause +4.5.23) shall be provided. +
    • +
  • +A Notification shall be sent +(as mandated by each concrete binding and including any optional +endpoint.receiverInfodefined by clause 5.2.22) to the endpoint specified by the +endpoint.urimember of the notification structure +defined by clause5.2.14. +The Notification content shall be JSONby default. However, this can be changed +to JSON-LD or GeoJSONby +means of the endpoint.acceptmember. +
    • +
  • +The notification.timesSent member shall be incremented by one. +
    • +
  • +The notification.lastNotification member shall be updated with a +timestamp representing the current date and time. +
    • +
  • +If the response to the notification request is 200 OK then +implementations shall: +
    • +
+
    +
  • +Update notification.lastSuccess with a timestamp representing the +current date and time. +
    • +
  • +Update notification.status to "ok". +
    • +
+
    +
  • +If the response to the +notification request is different than 200 OKthen implementations shall: +
    • +
+
    +
  • +Update notification.lastFailure with a timestamp representing the +current date and time. +
    • +
  • +Update notification. Status to "failed". +
    • +
+

5.9 Context +Source Registration

+

5.9.1 Introduction

+

As described in clause +5.2.9, Context Source +Registrations have a similar structure as Entities and are +generally handled in the same way. However, there are some aspects that +are specific to Registrations, in particular with respect to the +handling of required properties. Thus, the operation descriptions for +Registrations reference the respective operations for Entities and in +addition specify any deviations and additions that are necessary for +handling Context Source +Registrations.

+

Context Source Registrations +either contain information about Context +Sources providing the latest information or about Context Sources providing temporal +information, but not both. Context +Sources that can provide both thus have to use two separate Context Source Registrations. If no +temporal query is present, only Context +Source Registrations for Context +Sources providing latest information are returned, i.e. those +which do not specify time intervals used for temporal queries. If a +temporal query is present in a request for Context Source Registrations, only those +Context Source Registrations that +have a matching time interval are returned.

+

5.9.2 Register +Context Source

+

5.9.2.1 Description

+

This operation allows registering a context source within an NGSI-LD +system.

+

5.9.2.2 Use case +diagram

+

A Context Provider can register one or more context sources +within an NGSI-LD system as shown in Figure +5.9.2.2‑1.

+
+ +
+
+Figure 5.9.2.2-1: Register context source use case +
+

5.9.2.3 Input data

+

A data structure conforming to the CSourceRegistration data +type as mandated by clause +5.2.9.

+

5.9.2.4 Behaviour

+

Implementations shall generally exhibit the behaviour described in clause +5.6.1.4, but instead of any type of entities only Context Source Registrations can be +provided. Deviating from clause +5.6.1.4, implementations shall exhibit the following behaviour:

+
    +
  • +If the data types and restrictions expressed by clause +5.2.9 are not met by the Context Source +Registration, then an error of type BadRequestData shall +be raised. +
    • +
  • +If a contextSourceInfo array is defined and the restrictions +expressed by are not met by the Context +Source Registration, then an error of type BadRequestData +shall be raised. +
    • +
  • +If the Context Source to be +registered has its mode property defined as +exclusive, the following additional restrictions apply: +
    • +
+
    +
  • +If an exclusive or redirect Context Source Registration already matches +against the Entity ID (URI) and any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
  • +If an Entity already exists for the supplied Entity ID (URI) and the +existing Entity contains any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be +registered has its mode property defined as +redirect, the following additional restriction applies: +
    • +
+
    +
  • +If an existing Entity already matches the Context Source Registration, an error of +type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be +registered has its mode property defined as +auxiliary, the following additional restriction +applies: +
    • +
+
    +
  • +If the operations property is not defined as one of: "retrieveOps", "retrieveEntity" or "queryEntity", +or a combination thereof, an error of type BadRequestData shall +be raised. +
    • +
+
    +
  • +If the property expiresAt is not defined then the Context Source Registration shall last +forever (or until it is deleted from the system). +
    • +
  • +If expiresAt is a date and time in the past, an error of type +BadRequestData shall be raised. +
    • +
  • +If expiresAt is a date and time in the future, implementations +shall delete the Registration when this point in time is reached. +
    • +
  • +If the registration identifier, id, is contained in the Context Source Registration, +implementations have to check whether this is a valid identifier that +conforms to its policies and is unique within its scope. Otherwise, it +can replace the 'id' with a valid registration identifier. +
    • +
  • +Implementations shall add the concerned Context Source Registration and return an +'ok' response together with a registration identifier (id). +
    • +
  • +This id shall be used if NGSI-LD clients need to manage the +registration later. +
    • +
+

5.9.2.5 Output +data

+

One registration identifier (id) of type string, representing +a URI. Implementations shall ensure that registration identifiers are +unique within an NGSI-LD system.

+

5.9.3 Update Context Source +Registration

+

5.9.3.1 Description

+

This operation allows updating a Context +Source Registration in an NGSI-LD system.

+

5.9.3.2 Use case +diagram

+

A Context Provider can update a Context Source Registration in an NGSI-LD +system as shown in Figure +5.9.3.2‑1.

+
+ +
+
+Figure 5.9.3.2-1: Update context source registration use case +
+

5.9.3.3 Input data

+
    +
  • +Context Source Registration +identifier (URI), the target Context Source +Registration. +
    • +
  • +A JSON-LD document representing a Context +Source Registration Fragment (clause +5.4). +
    • +
+

5.9.3.4 Behaviour

+
    +
  • +If the target Context Source +Registration id (id) is not present or it is not a valid +URI, then an error of type BadRequestData shall be raised. +
    • +
  • +If a "contextSourceInfo" array is defined and the restrictions expressed +by are not met by the Context Source +Registration, then an error of type BadRequestData shall +be raised. +
    • +
  • +If the NGSI-LD System does not know about the target Context Source Registration, because there +is no existing Context Source +Registration whose id (URI) is equivalent, an error of type +ResourceNotFound shall be raised. +
    • +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.9 are not met by the Context Source +Registration Fragment, then an error of type +BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +If the Context Source Registration to +be updated has its mode property defined as +exclusive, the following additional restrictions apply: +
    • +
+
    +
  • +If an exclusive or redirect Context Source Registration already matches +against the Entity ID (URI) and any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
  • +If an Entity already exists for the supplied Entity ID (URI) and the +existing Entity contains any of the Attributes defined in the +registration, an error of type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source Registration to +be updated has its mode property defined as +redirect, the following additional restriction applies: +
    • +
+
    +
  • +If an existing Entity already matches the Context Source Registration, an error of +type Conflict shall be raised. +
    • +
+
    +
  • +If the Context Source to be updated +has its mode property defined as auxiliary, the +following additional restriction applies: +
    • +
+
    +
  • +If the operations property is not defined +as one of: "retrieveOps", "retrieveEntity" or "queryEntity", an error of type +BadRequestData shall be raised. +
    • +
+
    +
  • +Then, implementations shall modify the target Context Source Registration as mandated by +clause +5.5.8. +
    • +
+

5.9.3.5 Output +data

+

None.

+

5.9.4 Delete Context Source +Registration

+

5.9.4.1 Description

+

This operation allows deleting a Context +Source Registration from an NGSI-LD system.

+

5.9.4.2 Use case +diagram

+

A context provider can delete a context source registration from an +NGSI-LD system as shown in Figure +5.9.4.2‑1.

+
+ +
+
+Figure 5.9.4.2-1: Delete context source registration use case +
+

5.9.4.3 Input data

+

Registration identifier (URI) of the context source registration to +be deleted (target registration).

+

5.9.4.4 Behaviour

+
    +
  • +If the target context source registration id is not present or it is not +a valid URI, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target context source +registration, because there is no existing context source registration +whose id (URI) is equivalent, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Otherwise the context source registration shall be removed. +
    • +
+

5.9.4.5 Output +data

+

None.

+

5.10 Context +Source Discovery

+

5.10.1 Retrieve Context +Source Registration

+

5.10.1.1 Description

+

This operation allows retrieving a specific context source +registration from an NGSI-LD system.

+

5.10.1.2 Use case +diagram

+

A context consumer or a context provider can retrieve a specific +context source registration from an NGSI-LD system as shown in Figure +5.10.1.2‑1.

+
+ +
+
+Figure 5.10.1.2-1: Retrieve context source registration use case +
+

5.10.1.3 Input +data

+
    +
  • +Context source registration identifier (id) of the context source +registration to be retrieved (target registration). +
    • +
+

5.10.1.4 Behaviour

+
    +
  • +If the context source registration id (id) is not present or it +is not a valid URI, then an error of type BadRequestData shall be +raised. +
    • +
  • +If the NGSI-LD endpoint does not know about the target context source +registration, because there is no existing context source registration +whose id (URI) is equivalent, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +Term to URI expansion of Attribute names shall be observed as mandated +by clause +5.5.7. +
    • +
  • +Otherwise return a JSON-LD object representing the Context Source Registration as mandated by +clause +5.2.9. +
    • +
+

5.10.1.5 Output +data

+

A JSON-LD object representing the target context source registration +as mandated by clause +5.2.9.

+

5.10.2 Query Context Source +Registrations

+

5.10.2.1 Description

+

This operation allows discovering context source registrations from +an NGSI-LD system. The behaviour of the discovery of context source +registrations differs significantly from the querying of entities as +described in clause +5.7.2. The approach is that the client submits a query for entities +as described in clause +5.7.2, but instead of receiving the Entity information, it receives +a list of Context Source +Registrations describing Context +Sources that possibly have some of the requested Entity +information. This means that the requested Entities and Attributes are +matched against the 'information' property as described in .

+

If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without specified time intervals, are considered. If a +temporal query is present only Context +Source Registrations with matching time intervals, i.e. +observationInterval or managementInterval, are +considered.

+

5.10.2.2 Use case +diagram

+

A Context Consumer can discover context source registrations +that may be able to provide (part of) the context information specified +in the query from an NGSI-LD system as shown in Figure +5.10.2.2‑1.

+
+ +
+
+Figure 5.10.2.2-1: Discover context source registrations use case +
+

5.10.2.3 Input +data

+
    +
  • +A reference to a JSON-LD @context (optional). +
    • +
  • +A selector of Entity types as specified by clause +4.17. Both type name (short hand string) and fully qualified type +name (URI) are allowed (optional). +
    • +
  • +A list (one or more) of Entity identifiers (optional). +
    • +
  • +A list (one or more) of Attribute names (called query projection +attributes) (optional). +
    • +
  • +An id pattern as a regular expression (optional). +
    • +
  • +An NGSI-LD query (to filter out Entities by Attribute values, used here +to identify relevant attributes) as per clause +4.9 (optional). +
    • +
  • +An NGSI-LD geoquery (to filter out Entities by spatial relationships, +used here to identify relevant GeoProperties and for geographical +scoping) as per clause +4.10 (optional). +
    • +
  • +In the case of GeoJSON representation: +
    • +
+
    +
  • +The name of the GeoProperty attribute to use as the geometry for +the GeoJSON representation as mandated by clause +4.5.16 (optional). +
    • +
  • +A datasetId specifying which instance of the value is to be +selected if the GeoProperty value has multiple instances as +defined by clause +4.5.5 (optional). +
    • +
+
    +
  • +An NGSI-LD temporal query as per clause +4.11 (optional). +
    • +
  • +An NGSI-LD context source query as per clause +4.9 (optional). +
    • +
  • +A NGSI-LD Scope query as mandated by clause +4.19 (optional). +
    • +
  • +A limit to the number of Context Source +Registrations to be retrieved. See clause +5.5.9. +
    • +
  • +A specified language filter as per clause +4.15 (optional). +
    • +
+

It is not possible to retrieve a set of context source registrations +related to entities by only specifying desired Entity identifiers, +without further specifying restrictions on the entities' types or +attributes, either explicitly, via lists of Entity types or of Attribute +names, or implicitly, within an NGSI-LD query or geoquery.

+

5.10.2.4 Behaviour

+
    +
  • +Execute the behaviour defined in clause +5.5.4 on JSON-LD validation. +
    • +
  • +At least one of the following input data shall be provided: +
    • +
+
+a) selector of Entity Types; +
+
+b) list of Attribute names; +
+
+c) NGSI-LD Query; +
+
+d) NGSI-LD GeoQuery. +
+
+ If none of them is provided, then an error of type BadRequestData +shall be raised (too wide query). Attributes specified in NGSI-LD Query +or NGSI-LD GeoQuery shall be used for matching RegistrationInfo elements +in the same way as the attributes in the list of Attribute names. +
+
    +
  • +If the list of Entity identifiers includes a URI which it is not valid, +or the query, geoquery or temporal query are not syntactically valid (as +per clauses 4.9, +4.10 +and 4.11) +an error of type BadRequestData shall be raised. +
    • +
  • +Term to URI expansion of type and Attribute names shall be performed, as +mandated by clause +5.5.7. +
    • +
  • +Otherwise, implementations shall run a query that shall return context +source registrations that meet all the applicable +conditions: +
    • +
+
    +
  • +If present, the entity specification in the query consisting of a +combination of entity type selector and entity id/entity id pattern +(optional) matches an EntityInfo specified in a +RegistrationInfo of the information property in a context source +registration. If there is no EntityInfo specified in the +RegistrationInfo, the entity specification is considered +matching. This matching is further described in . +
    • +
  • +If present, at least one Attribute name specified in the query matches +one Property or Relationship in the RegistrationInfo element of +the information property in a context source registration. If no +Properties or Relationships are specified in the +RegistrationInfo, the Attribute names are considered matching. +This matching is further described in . +
    • +
  • +If present, the geoquery is matched against the GeoProperty +identified in the geoquery. If no GeoProperty is specified in the +geoquery, the default property is location. The geoquery matches +the GeoProperty specified in the Context Source Registration, if the +location directly matches or if the location possibly contains locations +that would match the geoquery. +
    • +
  • +If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without specified time intervals, are considered. +
    • +
  • +If a temporal query is present, only Context +Source Registrations with specified time intervals, i.e. +observationInterval or managementInterval are considered. +If the timeproperty is observedAt or no +timeproperty is specified in the temporal query (default: +observedAt), the temporal query is matched against the +observationInterval (if present). If the timeproperty is +createdAt, modifiedAt or deletedAt, the temporal +query is matched against the managementInterval (if present). If +the relevant interval is not present, there is no match: +
    • +
+
    +
  • +The semantics of the match is that the timeAt in the case of the +"before" and "after" relation is contained in or is an +endpoint of a time period included in the specified time interval. In +the case of the "between" relation there +is a match if there is an overlap between the interval specified by the +timeAt and endTimeAt and the specified time interval. +
    • +
+
    +
  • +If present, the conditions specified by the context source query filter +match the respective Context Source +Properties (as mandated by clause +4.9). +
    • +
  • +If present, the Scope query (as mandated by clause +4.19) is matched against the scope property. +
    • +
+
    +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.10.2.5 Output +data

+

A JSON-LD array of matching Context +Source Registrations as defined by clause +5.2.9. Instead of the original Context +Source Registration which may contain a lot of irrelevant +information, implementations should return filtered Context Source Registrations, which only +contain context source registration information relevant for the query, +in particular only matching RegistrationInfo elements.

+

5.11 Context Source +Registration Subscription

+

5.11.1 Introduction

+

Context Source Registration +Subscriptions in general work like context information subscriptions; +however, instead of resulting in notifications with context information, +the notifications contain Context Source +Registrations describing Context +Sources that can potentially provide the requested context +information. If no temporal query is present, only Context Source Registrations for Context Sources providing latest +information, i.e. without such time intervals, are considered. If a +temporal query is present only Context +Source Registrations with matching time intervals, i.e. +observationInterval or managementInterval, are +considered.

+

5.11.2 Create +Context Source Registration Subscription

+

5.11.2.1 Description

+

This operation allows creating a new Context Source Registration +Subscription.

+

5.11.2.2 Use case +diagram

+

A Context Source Subscriber +can subscribe to a new Context Source +Registration as shown in Figure +5.11.2.2‑1.

+
+ +
+
+Figure 5.11.2.2-1: Subscribe Context Source Registration use case +
+

5.11.2.3 Input +data

+
    +
  • +A data structure (represented in JSON-LD) conforming to the Subscription +data type as mandated by clause +5.2.12. +
    • +
+

5.11.2.4 Behaviour

+
    +
  • +The behaviour shall be as described in clause +5.8.1.4, restricted to the local case, with the following +exceptions: +
    • +
+
    +
  • +If an exclusive Context +Source Registration is being created: +
    • +
+
    +
  • +If an Entity matching the Registration already exists for this id (URI) +and attributes, an error of type Conflict shall be raised. +
    • +
  • +If an exclusive Context +Source Registration already exists for this id (URI) and +attributes, an error of type AlreadyExists shall be raised. +
    • +
+
    +
  • +If a redirect Context +Source Registration is being created and an Entity matching the +Registration already exists for this id (URI) and attributes, an error +of type Conflict shall be raised. +
    • +
  • +If all checks described in clause +5.8.1.4 pass, implementations shall add a new Context Source Registration Subscription. +The parameters of the created subscription shall be configured as +described in clause +5.8.1.4. +
    • +
  • +Instead of directly matching the entities and watched Attributes from +the Subscription with the Context +Source registrations, the entities specified in the subscription, +the watched Attributes and the Attributes specified in the notification +parameter are matched against the respective information property +of the Context Source registrations. +If either the watched Attributes or the Attributes in the notification +are not present or of length 0, all possible Attributes (if present in +the Context Source Registrations) for +matching entities match. This matching is further described in . +
    • +
  • +If present, the geoquery in the geoQ element is matched against the +GeoProperty of the subscription identified in the geoQ element. +If no GeoProperty is specified in the geoquery, the default +property is 'location'. The geoquery matches the GeoProperty +specified in the Context Source +Registration, if the location directly matches or if the location +possibly contains locations that would match the geoquery. +
    • +
  • +If no temporal query is present in the temporalQ element, only +Context Source Registrations for +Context Sources providing latest +information, i.e. without specified time intervals for +observationInterval or managementInterval, are considered. +
    • +
  • +If a temporal query in the temporalQ element is present, only +Context Source Registrations with +specified time intervals are considered. If the timeproperty is +"observedAt" or +no timeproperty is specified in the temporal query (default: +observedAt), the temporal query is matched against the +observationInterval (if present). If the timeproperty is +"createdAt", +"modifiedAt" +or "deletedAt", the temporal query is matched against the +managementInterval (if present). If the relevant interval is not +present, there is no match: +
    • +
+
    +
  • +The semantics of the match is that the timeAt in the case of the +"before" and "after" relation is contained in or is an +endpoint of a time period included in the specified time interval. In +the case of the "between" relation there +is a match if there is an overlap between the interval specified by the +timeAt and endTimeAt and the specified time interval. +
    • +
+
    +
  • +If present, the conditions specified by the context source filter match +the respective Context Source +Properties (as mandated by clause +4.9) +
    • +
+
    +
  • +If the subscription defines a timeInterval term, a +CsourceNotification (clause +5.3.2) with all matching Context Source +Registrations shall be sent periodically, initially on +subscription and when the time interval (in seconds) specified in such +value field is reached, independent of any changes to the set of Context Source registrations. +
    • +
  • +If timeInterval is not defined, initially on subscription and +whenever there is a change of a matching Context Source Registration (creation, +update, deletion), implementations shall post a new +CsourceNotification to the endpoint specified in the notification +parameters informing about this change by providing the Context Source Registration(s) together +with the appropriate trigger reason in the triggerReason member. +
    • +
  • +If present, the conditions specified by the context source query match +the respective Context Source +Properties (as mandated by clause +4.9). +
    • +
  • +If present, the Scope query (as mandated by clause +4.19) is matched against the scope property. +
    • +
+

5.11.2.5 Output +data

+

One subscription identifier (id) of type string, representing a URI. +Implementations shall ensure that subscription identifiers are unique +within an NGSI-LD system.

+

5.11.3 Update +Context Source Registration Subscription

+

5.11.3.1 Description

+

This operation allows updating an existing Context Source Registration +Subscription.

+

5.11.3.2 Use case +diagram

+

A context source subscriber can update a Context Source Registration Subscription as +shown in Figure +5.11.3.2‑1.

+
+ +
+
+Figure 5.11.3.2-1: Update Context Source Registration Subscription use +case +
+

5.11.3.3 Input +data

+
    +
  • +Subscription identifier (URI), the target Context Source Registration Subscription. +
    • +
  • +A JSON-LD document representing a Subscription Fragment. +
    • +
+

5.11.3.4 Behaviour

+
    +
  • +If the Subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the data types and restrictions expressed by clause +5.2.12 are not met by the Subscription Fragment, then an error of +type BadRequestData shall be raised. +
    • +
  • +Then, implementations shall modify the target subscription as mandated +by clause +5.5.8. +
    • +
  • +Finally, send a notification with all currently matching Context Source Registrations. +
    • +
+

5.11.3.5 Output +data

+

None.

+

5.11.4 Retrieve +Context Source Registration Subscription

+

5.11.4.1 Description

+

This operation allows retrieving an existing Context Source Registration +Subscription.

+

5.11.4.2 Use case +diagram

+

A Context Source subscriber can +retrieve a specific Context Source +Registration Subscription as shown in Figure +5.11.4.2‑1.

+
+ +
+
+Figure 5.11.4.2-1: Retrieve Context Source Registration Subscription use +case +
+

5.11.4.3 Input +data

+
    +
  • +Id (URI) of the subscription to be retrieved (target subscription). +
    • +
+

5.11.4.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the identifier provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall query the Context Source Registration Subscriptions +and obtain the subscription data to be returned to the caller. +
    • +
+

5.11.4.5 Output +data

+

A JSON-LD object representing the subscription details as mandated by +clause +5.2.12.

+

5.11.5 Query +Context Source Registration Subscriptions

+

5.11.5.1 Description

+

This operation allows querying existing Context Source Registration +Subscriptions.

+

5.11.5.2 Use case +diagram

+

A context source subscriber can query all existing Context Source Registration Subscriptions +as shown in Figure +5.11.5.2‑1.

+
+ +
+
+Figure 5.11.5.2-1: Query Context Source Registration Subscriptions use +case +
+

5.11.5.3 Input +data

+
    +
  • +A limit to the number of Context Source +Registration Subscriptions to be retrieved. See clause +5.5.9. +
    • +
+

5.11.5.4 Behaviour

+
    +
  • +The NGSI-LD System shall list all the existing Context Source Registration Subscriptions. +
    • +
  • +Pagination logic shall be in place as mandated by clause +5.5.9. +
    • +
+

5.11.5.5 Output +data

+

A list (represented as a JSON array) of JSON-LD objects each one +representing subscription details as mandated by clause +5.2.12.

+

5.11.6 Delete +Context Source Registration Subscription

+

5.11.6.1 Description

+

This operation allows deleting an existing Context Source Registration +Subscription.

+

5.11.6.2 Use case +diagram

+

A context source subscriber can delete a Context Source Registration Subscription as +shown in Figure +5.11.6.2‑1.

+
+ +
+
+Figure 5.11.6.2-1: Delete Context Source Registration Subscriptions use +case +
+

5.11.6.3 Input +data

+
    +
  • +A subscription identifier (URI). +
    • +
+

5.11.6.4 Behaviour

+
    +
  • +If the subscription Id is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the subscription id provided does not correspond to any existing +subscription in the system then an error of type ResourceNotFound +shall be raised. +
    • +
  • +Otherwise implementations shall delete the Context Source Registration Subscription +and no longer perform notifications concerning that Subscription. +
    • +
+

5.11.6.5 Output +data

+

None.

+

5.11.7 Notification behaviour

+

A Context Source Notification is a +message that allows a subscriber to be aware of the changes in the set +of Context Source Registrations +describing Context Sources that can +potentially provide the requested context information. Implementations +shall exhibit the behaviour described in clause +5.8.6 with the following exceptions:

+
    +
  • +If a subscription defines a timeInterval member, a +CsourceNotification (clause +5.3.2) shall be sent on initial subscription and periodically, when +the time specified time interval (in seconds) has elapsed, regardless of +any changes to the set of context source registrations. The +CsourceNotification message shall include all the Context Source Registrations whose +information property matches the entities and watched Attributes +or Attributes specified in the notification parameter and, if present, +have a matching geoquery. If either the watched Attributes or the +Attributes in the notification are not present or of length 0, all +possible Attributes (if present in the Context Source Registrations) for fitting +entities match. +
    • +
  • +If a subscription does not define a timeInterval term, the +csource notification shall be sent on initial subscription and whenever +there is a change in a matching csource registration. Such a change may +be triggered by the creation of a new matching csource registration, the +update of a csource registration (whether matching before the update, +after the update or in both cases) or the deletion of a matching csource +registration. The notification message shall include the matching +csource registration(s) together with the appropriate trigger reason in +the triggerReason member. +
    • +
  • +Instead of providing the original Context +Source Registration which may contain a lot of irrelevant +information, implementations should return filtered Context Source Registrations, which only +contain context source registration information relevant for the +subscription, in particular only matching RegistrationInfo +elements. +
    • +
  • +A csource notification shall be sent as follows: +
    • +
+
    +
  • +The structure of the csource notification message shall be as mandated +by clause +5.3.2. +
    • +
  • +A csource notification shall be +sent to the endpoint. +
    • +
  • +The notification.timesSent member shall be incremented by one. +
    • +
  • +The notification.lastNotification member shall be updated with +the current timestamp. +
    • +
  • +If the notification is sent successfully: +
    • +
+
    +
  • +Update notification.lastSuccess with the current timestamp. +
    • +
+
    +
  • +If the notification is not sent +successfully: +
    • +
+
    +
  • +Update notification.lastFailure with the current timestamp. +
    • +
  • +Update the subscription status to "failed". +
    • +
+

5.12 Matching Context Source +Registrations

+

When querying Context Source +Registrations as described in clause +5.10.2 and subscribing to Context Source +Registrations as described in clause +5.11.2, the Entities and/or Attributes specified in the request have +to be matched against the set of Context +Source Registrations, extracting the matching ones. This clause +describes this matching.

+

The relevant specification information in the query for Context Source Registrations are the +selector of Entity Types (if present), the list of Entity identifiers +(if present), the id pattern (if present) and the list of Attribute +names (if present). In the case of subscriptions to Context Source Registrations, it is the +Entities as specified in the array of type EntitySelector in the +Subscription, the watchedAttributes element of the +Subscription and the attributes specified as part of the +NotificationParams element of the Subscription. If the attributes +in the NotificationParams element are empty or not present, the +matching is done as if no attribute identifiers have been specified, +otherwise the combination of the watchedAttributes and the +attributes in the NotificationParams element are used as the +specified attribute identifiers for the matching.

+

Even though the way relevant Entities are specified differs in +queries and subscriptions, they consist of the same information, so for +the purpose of this clause, the specification of Entity Types or +Attributes refers to the relevant elements for matching, i.e. Entity +Types, Entity identifiers, id pattern and Attribute names. A +specification of Entity Types or Attributes shall contain at least one +of:

+
    +
  1. +selector of Entity Types; or +
    2. +
  2. +list of Attribute names. +
    3. +
+

A specification of Entity Types or Attributes matches a Context Source Registration if at least one +of the RegistrationInfo elements in the information +element matches. An Entity specification matches a +RegistrationInfo if the following conditions hold:

+
    +
  • +If present, the selector of Entity Types, Entity identifiers and id +pattern match at least one of the EntityInfo elements of the +RegistrationInfo (see below). +
    • +
  • +If present, the Attribute identifiers match the combination of +Properties and Relationships specified in the RegistrationInfo +(see below). +
    • +
+

An Entity specification consisting of selector of Entity Types, +Entity identifiers and id pattern matches an EntityInfo element +of the RegistrationInfo if the type selector matches the entity +types in the EntityInfo element and one of the following +conditions holds:

+
    +
  • +The EntityInfo contains neither an id nor an +idPattern. +
    • +
  • +One of the specified Entity identifiers matches the id in the +EntityInfo. +
    • +
  • +At least one of the specified Entity identifiers matches the +idPattern in the EntityInfo. +
    • +
  • +The specified id pattern matches the id in the EntityInfo. +
    • +
  • +Both a specified id pattern and an idPattern in the +Entity Info are present (since in the general case it is not +easily feasible to determine if there can be identifiers matching both +patterns). +
    • +
+

Attribute names match the combination of Properties and Relationships +if one of the following conditions hold:

+
    +
  • +No Attribute names have been specified (as this means all Attributes are +requested). +
    • +
  • +The combination of Properties and Relationships is empty (as this means +only Entities have been registered and the Context Sources may have matching Property +or Relationship instances). +
    • +
  • +If at least one of the specified attribute names matches a Property or +Relationship specified in the RegistrationInfo. +
    • +
+

If the request that triggered the matching includes a +datasetId parameter and the CSourceRegistration to be matched +contains a datasetId element, the CSourceRegistration should only +be considered matching, if both have at least one value in common. If +only one of them specifies a datasetId, it is considered a +match.

+

In the case of distributed operations (see clause +4.3.6.4), where a listing of all previously encountered Context Sources is supplied with the +request, no registration shall match if the CSourceRegistration +contextSourceAlias can be found within the listing of previously +encountered Context Sources.

+

Note that distributed queries (see clause +4.3.6.7), can be supplied with an EntityMap (see clause +4.5.25) which lists all Entity ids successfully matched during a +previous request. If the location of an EntityMap is passed into a +subsequent request, the retrieved EntityMap shall be used in preference +to the matching algorithm described above, provided that the EntityMap +is valid and has not expired.

+

5.13 Storing, Managing and +Serving @contexts

+

5.13.1 Introduction

+

Context Brokers optionally (see clause +4.3.5) offer the capability to store and serve @contexts to +clients. The stored @contexts may be managed by clients directly, +via the APIs specified in clause +5.13. Clients can store custom user @contexts at the Context +Broker, effectively using the Context Broker as a @context +server.

+

Moreover, in order to optimize performance, brokers may automatically +store and use the stored copies of common @contexts as a local cache, +downloading them just once, thus avoiding fetching them over and over +again at each NGSI-LD request. In order for the broker to understand if +a needed @context is already in the local storage or not, the +broker uses the URL, where the @context is originally hosted, as +an identifier for it in the local storage. Consequently, the broker has +no ability to cache @contexts that arrive to it as +embedded parts within the NGSI-LD documents, since they +are not uniquely (and implicitly) identified by any URL; Context Brokers only cache @contexts +that are referred to by means of explicit URLs (either in the HTTP Link +header or as URLs in the payload body). Thus, the recommended +best-practice, in order to exploit caching, is that clients do not embed +their user @contexts into their NGSI-LD +documents; instead clients should explicitly host their user +@contexts at their premises, or use the broker's capability to +host user @contexts on their behalf.

+

When an external @context is stored, either explicitly upon a +client's request or implicitly downloaded for caching purposes, the +Context Broker generates a unique local @context identifier. The +original @context's URL, if any, is stored alongside the +generated local id. The local id is then used for subsequent managing +operations on the specific @context, that are specified in +clauses 5.13.2 to +5.13.5. Moreover, the broker tags the entry with the current timestamp, +so that, subsequently, clients can check the timestamp before deciding +whether to force a refresh of the stored copy of the @context. +This is primarily intended as a means for clients to well-behave, thus +avoiding triggering continuous refresh of a stored @context on +the broker, for fear that it is not at the latest version.

+

Stored @contexts are flagged as one of three kinds: "Cached", "Hosted", "ImplicitlyCreated".

+
    +
  • +Cached:
    +@contexts implicitly and automatically fetched by the broker from +external URLs during normal NGSI-LD operations are flagged as "Cached". A locally unique identifier is +generated for each @context not already in the internal storage. +The downloaded content, its URL and the current time in UTC are stored +alongside the locally unique identifier. Implementations shall +periodically invalidate the "Cached" @contexts. Depending on the +binding of the NGSI-LD API to a specific protocol, that specific +protocol may provide explicit indications about expiration times of +cached content. In such cases, implementations shall comply with the +indications provided by the protocol. Implementations should assign a +heuristic expiration time when an explicit time is not specified. +Entries flagged as "Cached" shall not be served by brokers +on-demand, but only be used as a local cache to improve +performance. +
    • +
  • +Hosted:
    +@contexts that are explicitly added by users are flagged as "Hosted". These entries shall be served by +brokers on-demand. +
    • +
  • +ImplicitlyCreated:
    +@contexts that are implicitly, but ex-novo, created by the +broker as a result of a user request are flagged as "ImplicitlyCreated". For instance, when a +client creates a subscription using an @context that is an array, +and the broker has to notify with Content-Type "application/json", then the broker needs this @context +array to be hosted at a URL. Hence the broker has to create a new +@context that is an array, and it is going to be served from an +own URL. These entries shall be served by brokers on-demand. +
    • +
+

5.13.2 Add @context

+

5.13.2.1 Description

+

With this operation, a client can ask the broker to store the full +content of a specific @context, by giving it to the broker.

+

5.13.2.2 Use case +diagram

+

A client can add an @context to be stored within an NGSI-LD +system as shown in Figure +5.13.2.2‑1.

+
+ +
+
+Figure 5.13.2.2-1: Add @context use case +
+

5.13.2.3 Input +data

+

A JSON object that has a top-level field named @context, i.e. +a JSON object representing a JSON-LD "local context". As specified in +the JSON-LD specification [2], all extra information +located outside of the @context subtree in the referenced object +shall be discarded.

+

5.13.2.4 Behaviour

+

A new entry is created in the local storage and a locally unique +identifier is generated for it. The JSON object representing the +client-supplied @context and the current UTC time are stored +alongside the locally unique identifier. That identifier shall be given +back as a result in the output data. The entry is flagged as being of +kind "Hosted".

+

The behaviour described in clause +5.5.4 about JSON and JSON-LD validation shall be applied in case of +invalid @context.

+

5.13.2.5 Output +data

+

The locally unique identifier that identifies the @context in +the broker's internal storage.

+

5.13.3 List +@contexts

+

5.13.3.1 Description

+

With this operation a client can obtain a list of URLs that represent +all of the @contexts stored in the local context store of the +broker. Each URL can be used to download the corresponding +@context, and, in case the @context's kind is "Cached", it shall be the original URL the +broker downloaded the @context from.

+

In case a details flag is set to true, the client +obtains a list of JSON objects, each representing information (metadata) +about an @context currently stored by the broker. Each JSON +object contains information about the @context's original URL (if +any), its local identifier in the broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), its creation timestamp, +its expiry date (if "Cached"), and +additional optional information.

+

5.13.3.2 Use case +diagram

+

A client can list all @contexts stored within an NGSI-LD +system as shown in Figure +5.13.3.2‑1.

+
+ +
+
+Figure 5.13.3.2-1: List @contexts use case +
+

5.13.3.3 Input +data

+
    +
  • +A kind filter indicating the kind of stored @contexts that +are to be included in the output list. Currently, possible kinds are +"Cached", "Hosted" and "ImplicitlyCreated" (optional). +
    • +
  • +A boolean details flag indicating that detailed JSON objects +representing metadata about the stored @contexts instead of +simple URLs are requested (optional). +
    • +
+

5.13.3.4 Behaviour

+

The broker shall provide a URL or JSON object for each +@context currently stored in the internal broker's storage, that +match the filter. If no filter is specified, all kinds are included.

+

5.13.3.5 Output +data

+

A list of URLs, or a list of resulting JSON objects containing the +following fields:

+
    +
  • +URL; +
    • +
  • +localId; +
    • +
  • +kind; +
    • +
  • +timestamp; +
    • +
  • +lastUsage [OPTIONAL]; +
    • +
  • +numberOfHits [OPTIONAL]; +
    • +
  • +extraInfo [OPTIONAL, used by implementations to report any kind of +custom information]. +
    • +
+

5.13.4 Serve +@context

+

5.13.4.1 Description

+

With this operation a client can obtain the full content of a +specific @context (only for @contexts of kind "Hosted" or "ImplicitlyCreated"), which is currently stored +in the broker's internal storage, or its metadata (for all kinds of +stored @contexts).

+

5.13.4.2 Use case +diagram

+

A client can request the broker to serve a specific @context +stored within the NGSI-LD system as shown in Figure +5.13.4.2‑1.

+
+ +
+
+Figure 5.13.4.2-1: Serve @context use case +
+

5.13.4.3 Input +data

+
    +
  • +The locally unique identifier that identifies the desired +@context in the broker's internal storage. Such unique +identifiers are obtained by the client as a result of either a "Add +@context" (clause +5.13.2) API operation or of a "List @contexts" (clause +5.13.3) API operation. For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. +
    • +
  • +A boolean details flag indicating that a JSON object representing +metadata about the @context, instead of the full content, is +requested (optional). +
    • +
+

5.13.4.4 Behaviour

+
    +
  • +If details is set to false, or details is not +present, the broker shall give back the full content of the +@context that corresponds to the indicated local identifier, +serving it from its internal storage, if the @context that +corresponds to the indicated local identifier is of kind "Hosted" or "ImplicitlyGenerated". It shall give back +OperationNotSupported error if it is of kind "Cached". It shall give back +ResourceNotFound if the identifier is not found. +
    • +
  • +Otherwise, if details is set to true, the broker shall +give back metadata about the @context that corresponds to the +indicated local identifier. It shall give back ResourceNotFound +error if the identifier is not found. +
    • +
+

5.13.4.5 Output +data

+

The full content of the indicated @context (or its metadata as +specified in clause +5.13.3.5), or ResourceNotFound/OperationNotSupported +errors.

+

5.13.5 Delete +and Reload @context

+

5.13.5.1 Description

+

With this operation, a client supplies a local identifier to the +broker, indicating a stored @context, that the broker shall +remove from its storage. For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. If the entry in the local +storage that corresponds to the identifier is itself an array of +@contexts, this operation will not delete the +children, i.e. the @contexts in the array, but just the +entry.

+

5.13.5.2 Use case +diagram

+

A client can request the broker to delete (and optionally reload) a +specific @context stored within the NGSI-LD system as shown in Figure +5.13.5.2‑1.

+
+ +
+
+Figure 5.13.5.2-1: Delete and Reload @context use case +
+

5.13.5.3 Input +data

+
    +
  • +The locally unique identifier that identifies the desired +@context in the broker's internal storage. For @contexts +of kind "Cached" this can also be the +original URL the broker downloaded the @context from. +
    • +
  • +A reload boolean flag indicating that reloading of the +@context shall be attempted (optional). +
    • +
+

5.13.5.4 Behaviour

+
    +
  • +If the @context identifier is not supplied, then an error of type +BadRequestData shall be raised. +
    • +
  • +If the @context identifier does not correspond to any existing +entry in the @context storage, then an error of type +ResourceNotFound shall be raised. +
    • +
  • +If reload is true and the kind of the @context is +"Cached", implementations shall try to +re-download the identified @context from its original URL, before +removing it from the internal storage. If downloading fails, or the +downloaded @context is invalid according to JSON and JSON-LD +validation of clause +5.5.4, then an error of type LdContextNotAvailable shall be +raised. More detailed information about the errors shall be specified in +the ProblemDetails (see IETF RFC 7807 [10]) field of the response. +In case of any error, the operation ends without removing the existing +@context. Otherwise, the existing @context is replaced +with the newly downloaded one. +
    • +
  • +If reload is true and the kind of the @context is +not "Cached", +implementations shall return a BadRequestData error. +
    • +
  • +If reload is false (or reload is not supplied), +implementations shall remove from the internal storage the +@context that corresponds to the given identifier. The local +identifier is used for finding the @contexts in the internal +broker's storage. If the local identifier is not in the storage, a +ResourceNotFound error shall be raised. +
    • +
+

5.13.5.5 Output +data

+

None.

+

5.14 Context Source Entity +Mapping

+

5.14.1 Retrieve +EntityMap

+

5.14.1.1 Description

+

With this operation a client can obtain a cached EntityMap which is +currently stored in the broker's internal storage, or memory.

+

5.14.1.2 Use case +diagram

+

A client can request the broker to retrieve a specific EntityMap +within the NGSI-LD system as shown in Figure +5.14.1.2‑1.

+
+ +
+
+Figure 5.14.1.2-1: Retrieve EntityMap +
+

5.14.1.3 Input +data

+
    +
  • +EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). +
    • +
+

5.14.1.4 Behaviour

+
    +
  • +If the Entity ID is not present or it is not a valid URI, then an error +of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +Otherwise, return a JSON-LD object representing the EntityMap as +mandated by clause +5.2.39. +
    • +
+

5.14.1.5 Output +data

+

A JSON-LD object representing the target EntityMap as mandated by clause +5.2.39.

+

5.14.2 Update +EntityMap

+

5.14.2.1 Description

+

This operation allows performing a partial update on an +NGSI-LD EntityMap. A partial update only changes the elements +provided in the EntityMap, leaving the rest as they are.

+

5.14.2.2 Use case +diagram

+

A client can request the broker to update an EntityMap which is +currently stored in the broker's internal storage as shown in Figure +5.14.2.2‑1.

+
+ +
+
+Figure 5.14.2.2-1: Update EntityMap +
+

5.14.2.3 Input +data

+
    +
  • +EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). +
    • +
  • +A JSON-LD document representing an EntityMap. +
    • +
+

5.14.2.4 Behaviour

+
    +
  • +If the EntityMap ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +Perform an update operation on the target EntityMap using the fields +specified within then JSON-LD document. +
    +
    + +
    • +
+

5.14.2.5 Output +data

+

None

+

5.14.3 Delete +EntityMap

+

5.14.3.1 Description

+

This operation allows deleting an NGSI-LD EntityMap.

+

5.14.3.2 Use case +diagram

+

A client can request the broker to completely delete an EntityMap +held within the NGSI-LD system as shown in Figure +5.14.3.2‑1.

+
+ +
+
+Figure 5.14.3.2-1: Delete EntityMap +
+

5.14.3.3 Input +data

+
    +
  • +EntityMap ID (URI) of the EntityMap to be retrieved (target EntityMap). +
    • +
+

5.14.3.4 Behaviour

+
    +
  • +If the EntityMap ID is not present or it is not a valid URI, then an +error of type BadRequestData shall be raised. +
    • +
  • +If the NGSI-LD endpoint does not know about a matching EntityMap for the +EntityMap ID, then an error of type ResourceNotFound shall be +raised. +
    • +
  • +The EntityMap shall be removed from the broker's internal storage, or +memory. +
    • +
+

5.14.4.5 Output +data

+

None.

+

5.15 Context Source Identity +Information

+

5.15.1 Retrieve +Context Source Identity Information

+

5.15.1.1 Description

+

With this operation, a client can obtain Context Source identity information which +uniquely defines the Context Source +itself. In the multi-tenancy use case (see clause +4.14), a client can obtain identify information about a specific +Tenant within a Context Source.

+

5.15.1.2 Use case +diagram

+

A client can request the broker to retrieve identity information about a specific +Context Source within the NGSI-LD +system as shown in figure +5.15.1.2‑1.

+
+ +
+
+Figure 5.15.1.2-1: Retrieve Context Source Identity Information +
+

5.15.1.3 Input +data

+

None.

+

5.15.1.4 Behaviour

+
    +
  • +If the Context Source is unable to +supply identity information about itself, then error of type +NotImplemented shall be raised. +
    • +
  • +Return a JSON-LD object representing the identity of the Context Source itself as mandated by clause +5.2.40. This can also include additional configurational data +dependent on the specificContext +Source implementation. +
    • +
+

5.14.1.5 Output +data

+
    +
  • +A JSON-LD object representing the identity of the Context Source as mandated by clause +5.2.40. +
    • +
+
+ + diff --git a/public/12-tabapi-http-binding.html b/public/12-tabapi-http-binding.html new file mode 100644 index 0000000000000000000000000000000000000000..22d9a6bafae55a18b8b1c84cb5ee5eb3a295ce35 --- /dev/null +++ b/public/12-tabapi-http-binding.html @@ -0,0 +1,16283 @@ + + + + + + + 6 API HTTP Binding + + + + + + + +
+

6 API HTTP Binding

+

6.1 Introduction

+

This clause defines the resources and operations of the NGSI-LD API. +The NGSI-LD API is structured in terms of HTTP [3], [4] verbs, request and response +payload bodies.

+

A non-normative OAS specification [i.12] of the referred HTTP +binding can be found at [i.14].

+

6.2 Global Definitions +and Resource Structure

+

All resource URIs of this API shall have the following root:

+
    +
  • +{apiRoot}/{apiName}/{apiVersion}/ +
    • +
+
+NOTE 1: The apiRoot discovery process is out of the scope of the +present document. +
+
+NOTE 2: The apiRoot for Context +Source related aspects and the apiRoot for general +Entity-related aspects can be different, e.g. the Context Source related aspects can be +implemented by a Context Registry as +shown for the distributed and federated architectures (see clause +4.3), whereas the Entity-related aspects would be implemented by a +Context Broker. +
+
+NOTE 3: The apiRoot for Context +Source related aspects and the apiRoot for general +Entity-related aspects can be different than the apiRoot for +temporal aspects, e.g. the temporal aspects can be implemented by an +NGSI-LD subsystem specialized in historical data. +
+

The apiRoot includes the scheme ("http" or "https"), host and +optional port, and an optional prefix string. The API shall support HTTP +over TLS (also known as HTTPS – see IETF RFC 2818 [18]). TLS version 1.2 as +defined by IETF RFC 5246 [19] shall be supported. HTTP +without TLS is not recommended.

+

The apiName shall be set to "ngsi-ld" and the apiVersion shall be +set to "v1" for the present document.

+

All resource URIs are defined relative to the above root URI. The +structure of the resources under the root URI is shown in Figure 6.2‑1 and +methods defined on them are shown in Table 6.2‑1.

+
+ +
+
+Figure 6.2-1: Resource URI structure of the NGSI-LD API +
+
+Table 6.2-1: Resources and HTTP methods defined on them +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Resource Name +
+Resource URI +
+HTTP Method +
+Meaning +
+Clauses +
+Entity List +
+/entities/ +
+POST +
+Entity creation +
+5.6.1; 6.4.3.1 +
+GET +
+Query entities +
+5.7.2; 6.4.3.2 +
+Entity by id +
+/entities/{entityId} +
+GET +
+Entity retrieval by id +
+5.7.1; 6.5.3.1 +
+DELETE +
+Entity deletion by id +
+5.6.6; 6.5.3.2 +
+PATCH +
+Entity merge by id +
+5.6.17; 6.5.3.4 +
+PUT +
+Entity replacement by id +
+5.6.18; 6.5.3.3 +
+Attribute List +
+/entities/{entityId}/attrs/ +
+POST +
+Append Attributes to Entity +
+5.6.3; 6.6.3.1 +
+PATCH +
+Update Attributes of an Entity +
+5.6.2; 6.6.3.2 +
+Attribute by id +
+/entities/{entityId}/attrs/{attrId} +
+PATCH +
+Partial Attribute update +
+5.6.4; 6.7.3.1 +
+DELETE +
+Attribute deletion +
+5.6.5; 6.7.3.2 +
+PUT +
+Attribute replacement +
+5.6.19; 6.7.3.3 +
+Subscriptions List +
+/subscriptions/ +
+POST +
+Create Subscription +
+5.8.1; 6.10.3.1 +
+GET +
+Retrieve list of Subscriptions +
+5.8.4; 6.10.3.2 +
+Subscription by Id +
+/subscriptions/{subscriptionId} +
+GET +
+Subscription retrieval by id +
+5.8.3; 6.11.3.1 +
+PATCH +
+Subscription update by id +
+5.8.2; 6.11.3.2 +
+DELETE +
+Subscription deletion by id +
+5.8.5; 6.11.3.3 +
+Entity Types +
+/types/ +
+GET +
+Retrieve available entity types +
+5.7.5 and 5.7.6; 6.25.3.1 +
+Entity Type +
+/types/{type} +
+GET +
+Details about available entity type +
+5.7.7; 6.26.3.1 +
+Attributes +
+/attributes/ +
+GET +
+Available attributes +
+5.7.8 and 5.7.9; 6.27.3.1 +
+Attribute +
+/attributes/{attrId} +
+GET +
+Details about available attribute +
+5.7.10; 6.28.3.1 +
+Context source registration list +
+/csourceRegistrations/ +
+POST +
+Csource registration creation +
+5.9.2; 6.8.3.1 +
+GET +
+Discover Csource registrations +
+5.10.2; 6.8.3.2 +
+Context source registration by Id +
+/csourceRegistrations/{registrationId} +
+GET +
+Csource registration retrieval by id +
+5.10.1; 6.9.3.1 +
+PATCH +
+Csource registration update by id +
+5.9.3; 6.9.3.2 +
+DELETE +
+Csource registration deletion by id +
+5.9.4; 6.9.3.3 +
+Context source registration subscription list +
+/csourceSubscriptions/ +
+POST +
+Create subscription to Csource registration +
+5.11.2; 6.12.3.1 +
+GET +
+Retrieval of list of subscription to Csource registration +
+5.11.5; 6.12.3.2 +
+Context source registration subscription by Id +
+/csourceSubscriptions/{subscriptionId} +
+GET +
+Csource registration subscription retrieval by id +
+5.11.4; 6.13.3.1 +
+PATCH +
+Csource registration subscription update by id +
+5.11.3; 6.13.3.2 +
+DELETE +
+Csource registration subscription deletion by id +
+5.11.6; 6.13.3.3 +
+Entity Operations. Create +
+/entityOperations/create +
+POST +
+Batch Entity creation +
+5.6.7; 6.14.3.1 +
+Entity Operations. Upsert +
+/entityOperations/upsert +
+POST +
+Batch Entity creation or update (upsert) +
+5.6.8; 6.15.3.1 +
+Entity Operations. Update +
+/entityOperations/update +
+POST +
+Batch Entity update +
+5.6.9; 6.16.3.1 +
+Entity Operations. Delete +
+/entityOperations/delete +
+POST +
+Batch Entity deletion +
+5.6.10; 6.17.3.1 +
+Entity Operations. Query +
+/entityOperations/query +
+POST +
+Query entities based on POST +
+5.7.2; 6.23.3.1 +
+Entity Operations. +
+
+Merge +
+/entityOperations/merge +
+POST +
+Batch Entity merge +
+5.6.20; 6.31.3.1 +
+Temporal Evolution of Entities +
+/temporal/entities/ +
+POST +
+Temporal Evolution of an Entity creation +
+5.6.11; 6.18.3.1 +
+GET +
+Query Temporal Evolution of Entities +
+5.7.4; 6.18.3.2 +
+Temporal Evolution of an Entity by id +
+/temporal/entities/{entityId} +
+GET +
+Temporal Evolution of an Entity retrieval by id +
+5.7.3; 6.19.3.1 +
+DELETE +
+Temporal Evolution of an Entity deletion by id +
+5.6.16; 6.18.3.2 +
+Temporal Representation of Attribute List +
+/temporal/entities/{entityId}/attrs/ +
+POST +
+Temporal Evolution of Attribute of an Entity instance addition +
+5.6.12; 6.20.3.1 +
+Temporal Representation of Attribute by id +
+/temporal/entities/{entityId}/attrs/{attrId} +
+DELETE +
+Attribute from Temporal Evolution of an Entity deletion +
+5.6.13; 6.21.3.1 +
+Temporal Representation of Attribute Instance by id +
+/temporal/entities/{entityId}/attrs/{attrId} /{instanceId} +
+PATCH +
+Attribute Instance from Temporal Evolution of an Entity update by +instance id +
+5.6.14; 6.22.3.1 +
+DELETE +
+Attribute Instance from Temporal Evolution of an Entity deletion by +instance id +
+5.6.15; 6.22.3.2 +
+Temporal Query Operation +
+/temporal/entityOperations/query +
+POST +
+Query Temporal Evolution of Entities based on POST +
+5.7.4; 6.24.3.1 +
+Add and List @context +
+/jsonldContexts +
+POST +
+Add a user @context to the internal cache +
+5.13.2; 6.29.3.1 +
+GET +
+List all cached @contexts +
+5.13.3; 6.29.3.2 +
+Serve, Delete and Reload @context +
+/jsonldContexts/{contextId} +
+GET +
+Serve one specific user @context +
+5.13.4; 6.30.3.1 +
+DELETE +
+Delete one specific @context from internal cache, possibly re-inserting +a freshly downloaded copy of it +
+5.13.5; 6.30.3.2 +
+Retrieve, Update and Delete Entity Maps +
+/entityMaps/{entityMapId} +
+GET +
+EntityMap Retrieval by id +
+5.14.1; 6.32.3.1 +
+PATCH +
+EntityMap Update by id +
+5.14.2; 6.32.3.2 +
+DELETE +
+EntityMap Deletion by id +
+5.14.3; 6.32.3.3 +
+Retrieve Context Source Identity Information +
+/info/sourceIdentity +
+GET +
+Context Source Identity Retrieval +
+5.15.1; 6.33.3.1 +
+

6.3 Common +Behaviours

+

6.3.1 Introduction

+

This clause extends the API common behaviours to the particularities +of the HTTP REST binding. For each operation implementations shall +exhibit the common behaviours as specified by clause +5.5 and the behaviours defined by the present clause.

+

6.3.2 Error Types

+

This clause associates API error types (which shall be contained in +the response payload body) defined by clause +5.5.2 with HTTP status codes as shown in Table 6.3.2‑1.

+
+Table 6.3.2-1: Mapping of error types to HTTP status codes +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Error Type +
+HTTP status +
+https://uri.etsi.org/ngsi-ld/errors/InvalidRequest +
+400 +
+https://uri.etsi.org/ngsi-ld/errors/BadRequestData +
+400 +
+https://uri.etsi.org/ngsi-ld/errors/AlreadyExists +
+409 +
+https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported +
+422 +
+https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound +
+404 +
+https://uri.etsi.org/ngsi-ld/errors/InternalError +
+500 +
+https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery +
+403 +
+https://uri.etsi.org/ngsi-ld/errors/TooManyResults +
+403 +
+https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable +
+504 +
+https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport +
+501 +
+https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant +
+404 +
+

In addition, implementations shall support the standard specific +errors of HTTP bindings, such as the following:

+
    +
  • +"Method Not Allowed" (405) which shall be raised when a client invokes a +wrong HTTP verb over a resource. Implementations shall provide the +allowed HTTP methods as mandated by IETF RFC 7231 [3] in section 6.5.5. +
    • +
  • +"Request Entity too large" (413) which shall be raised when the HTTP +input data stream provided by a client was too large i.e. too many +bytes. +
    • +
  • +"Length required" (411) which shall be raised when an HTTP request +provided by a client does not define the "Content-Length" HTTP header. +
    • +
  • +"Unsupported Media Type" (415) which shall be raised when an HTTP +request payload body (as per the "Content-Type" header) it is not "application/json" nor "application/ld+json". +
    • +
  • +"Not Acceptable" 406) which shall be raised +when the response media types that are acceptable by a client (as per +the "Accept" header) do not include or expand to "application/json" nor "application/ld+json". +
    • +
+

6.3.3 Reporting +errors

+

When an API operation results in an error, implementations shall +return an HTTP response as follows:

+
    +
  • +Content-Type: application/json. +
    • +
  • +HTTP Status Code: As per clause 6.3.2 +depending on error type. +
    • +
  • +Payload body: A JSON object including all the terms defined by clause +5.5.3. +
    • +
+

6.3.4 HTTP +request preconditions

+

For POST, PATCH and PUT HTTP requests implementations shall check the +following preconditions:

+
    +
  • +Content-Type header shall be "application/json" or "application/ld+json". +
    • +
  • +Content-Length header shall include the length of the request payload +body. +
    • +
+

For PATCH HTTP requests "application/merge-patch+json" is allowed as +Content-Type, as mandated by IETF RFC 7396 [16]. Implementations shall +interpret such MIME type as equivalent to "application/json".

+

For GET HTTP requests implementations shall check the following +preconditions:

+
    +
  • +Accept header shall include (or define a media range that can be +expanded to): +
    • +
+
    +
  • +"application/json" +
    • +
  • +"application/ld+json" +
    • +
  • +"application/geo+json" +
    • +
+

The order of the list above is significant. If the Accept header can +be expanded to more than one of the options of the list, the first one +of the list shall be selected, unless amended by the HTTP Accept header +processing rules, e.g. the presence of a "q" parameter indicating a relative weight, (as +mandated by IETF RFC 7231 [3], section 5.3.2) require +otherwise.

+

If the Accept header is not present, "application/json" shall be assumed.

+

If an incoming HTTP request does not meet the preconditions stated +above, an HTTP error response of type InvalidRequest shall be +returned, with the following exceptions:

+
    +
  • +"Content-Length" HTTP header absence, shall result in just a +411 HTTP status code (without any payload body). +
    • +
  • +Unsupported Media Type, i.e. "Content-Type" header is not "application/json" nor "application/ld+json", shall result in just a +415 HTTP status code (without any payload body). +
    • +
  • +Not Acceptable Media Type, i.e. "Accept" header does not imply "application/json" nor "application/ld+json", shall result in just a +406 HTTP status code and the body of the message shall +contain the list of the available representations of the resources. +
    • +
+

Notwithstanding the above, if the Accept Header is set to "application/geo+json":

+
    +
  • +For Context Information Consumption operations only, specifically +"Retrieve Entity" (see clause +5.7.1) and "Query Entity" (clause +5.7.2) GeoJSON is considered as an acceptable content type and a +GeoJSON payload will be returned. +
    • +
  • +For all other operations, the request will result in a Not Acceptable +Media Type error, returning a 406 HTTP status code and +the body of the message shall contain the list of the available +representations of the resources. +
    • +
+

6.3.5 JSON-LD +@context resolution

+

In the HTTP REST binding, implementations shall resolve the JSON-LD +@context associated to an incoming HTTP request as follows:

+
    +
  • +If the request verb is GET or DELETE, then the associated JSON-LD +@context shall be obtained from a Link header [7] as mandated by JSON-LD +[2], section 6.2. In +the absence of such Link header, then the associated @context +shall be the default JSON-LD @context. +
    • +
+
+EXAMPLE: The structure of the referred Link header is shown below. The +first component (between < >) is a +dereferenceable URI pointing to the JSON-LD document which contains the +@context to be used to expand the terms used by the corresponding +operation. The second parameter is a fixed, non-dereferenceable URI used +to denote a unique identifier and semantics for this header (marking it +as a link to a JSON-LD @context). The third and final parameter +flags the MIME type of the linked resource (JSON-LD). +
+
+ Link: <http://json-ld.org/contexts/person.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json". +
+
    +
  • +If the request verb is POST, PATCH or PUT and the Content-Type header is +"application/json", then the +@context shall be obtained from a Link Header as mandated by +JSON-LD [2], section +6.2. In the absence of such Link Header, then the @context shall +be the default @context. In any case, if the request payload body +(as JSON) contains a @context term, then an HTTP error response +of type BadRequestData shall be raised. +
    • +
  • +If the request verb is POST, PATCH or PUT and the Content-Type header is +"application/ld+json", then the +associated @context shall be obtained from the request payload +body itself. If no @context can be obtained from the request +payload body, then an HTTP error response of type BadRequestData +shall be raised. In any case, the presence of a JSON-LD Link header in +the incoming HTTP request when the Content-Type header is "application/ld+json" shall result in an HTTP +error response of type BadRequestData. +
    • +
+

In summary, from a developer's perspective, for POST, PATCH and PUT +operations, if MIME type is "application/ld+json", then the associated +@context shall be provided only as part of the request payload +body. Likewise, if MIME type is "application/json", then the associated +@context shall be provided only by using the JSON-LD Link header. +No mixes are allowed, i.e. mixing options shall result in HTTP response +errors. Implementations should provide descriptive error messages when +these situations arise.

+

In contrast, GET and DELETE operations always take their input +@context from the JSON-LD Link Header.

+

6.3.6 HTTP response common +requirements

+

Implementations shall honour the Accept header provided by HTTP +requests as mandated by clause +6.3.4:

+
    +
  • +If the target response's MIME type is "application/json" such response shall include +a Link to the associated JSON-LD @context as mandated by [2], section 6.2. +
    • +
  • +If the target response's MIME type is "application/ld+json", then the response +payload body provided by the HTTP response shall include a JSON-LD +@context. +
    • +
  • +If the target response's MIME type is "application/geo+json" and the Prefer Header +[26] is omitted or +set to "body=ld+json", then the response +payload body provided by the HTTP response shall include a JSON-LD +@context, and the representation of the entities shall be in +GeoJSON format in the response payload body. +
    • +
  • +If the target response's MIME type is "application/geo+json" and the Prefer Header +[26] is set to "body=json" such response shall include a Link +to the associated JSON-LD @context as mandated by [2], section 6.2 and the +representation of the entities shall be in GeoJSON format in the +response payload body, and @context shall be omitted from the +payload body. +
    • +
+

Operations that result in an error that return a payload shall always +respond with MIME type "application/json", regardless of the +Accept header. It is assumed that if a client application understands +any of the supported MIME types, the application shall understand "application/json" errors.

+

Operations where the response payload body is not present such as +successful POST, or PATCH or PUT operations and all error responses, do +not include the Link header in the response. Only Fully Qualified Names +shall be used in the payload body of error responses, as there is no +context present.

+

No Content-Length HTTP header shall be present if the response code +is 204.

+

6.3.7 Representation of Entities

+

For HTTP GET operations performed over the resource /entities and all +of its sub-resources, Context Broker +implementations shall support the parameter specified in Table 6.3.7‑1, +which specifies all possible supported representations formats.

+

In contrast, at a minimum, registered Context Source implementations shall +support the normalized representation of Entities as default. When a +registered Context Source is unable +to support additional representations, a 501 Not Implemented Error shall +be raised.

+
+Table 6.3.7-1: Entity representations: format + options parameter +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+When its value is "normalized", a +normalized representation of Entities shall be provided as defined by clause +4.5.1, with Attributes returned in the normalized representation as +defined in clauses 4.5.2.2, +4.5.3.2, +4.5.18.2 +and 4.5.20.2. +
+
+ +
+
+When its value is "concise", a concise +lossless representation of Entities shall be provided as defined by clause +4.5.1. with Attributes returned in the concise representation as +defined in clauses 4.5.2.3, +4.5.3.3, +4.5.18.3 +and 4.5.20.3. +In this case the Context Broker will +return data in the most concise lossless representation possible, for +example removing all Attribute type members. +
+
+ +
+
+When its value is "simplified" (or its synonym "keyValues"). a simplified representation of +Entities shall be provided as defined by clause +4.5.4 +
+
+ +
+
+If the Accept Header is set to "application/geo+json" the response will be in +simplified GeoJSON format as defined by clause +4.5.17. +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword "normalized", a normalized representation of +Entities shall be provided as defined by clause +4.5.1, with Attributes returned in the normalized representation as +defined in clauses 4.5.2.2, +4.5.3.2, +4.5.18.2 +and 4.5.20.2. +
+
+ +
+
+When its value includes the keyword "concise", a concise lossless representation of +Entities shall be provided as defined by clause +4.5.1. with Attributes returned in the concise representation as +defined in clauses 4.5.2.3, +4.5.3.3, +4.5.18.3 +and 4.5.20.3. +In this case the Context Broker will +return data in the most concise lossless representation possible, for +example removing all Attribute type members. +
+
+ +
+
+When its value includes the keyword "simplified" (or its synonym "keyValues"). a simplified representation of +Entities shall be provided as defined by clause +4.5.4. +
+
+ +
+
+If the Accept Header is set to "application/geo+json" the response will be in +simplified GeoJSON format as defined by clause +4.5.17. +
+

6.3.8 Notification behaviour

+

In the HTTP binding a notification that is triggered by a +subscription shall be sent by issuing an HTTP POST request targeted to +the value of notification.endpoint.uri member of the subscription +structure (defined by clauses 5.2.12, +5.2.14 +and 5.2.15). For +the HTTP binding, the protocol part of the endpoint URI is http or +https. In case the optional MQTT notification binding (clause +7) is supported, the protocol part of the endpoint URI can also be +mqtt or mqtts. The MIME type associated to the POST +request shall be "application/json" by +default. However, this can be changed to "application/ld+json", or "application/geo+json" by means of the +endpoint.accept member.

+

If the target MIME type is "application/json" then the HTTP notification +request shall include a Link header with a reference to the +corresponding JSON-LD @context as mandated by the JSON-LD +specification [2], +section 6.2 (to the default JSON-LD @context if none +available).

+

If the optional array (of KeyValuePair type, as defined by clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new custom HTTP header for each member +named "key" of the key, value pairs that make up the array shall be +generated and included in the HTTP POST's list of headers. The content +of each custom header shall be set equal to the content of the +corresponding "value" member of the KeyValuePair. "Key" and +"value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

If the target MIME type is "application/geo+json" and the +notification.endpoint.receiverInfo member contains a key "Prefer" whose value is set to "body=json" then the HTTP notification request +shall include a Link header with a reference to the corresponding +JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the +default JSON-LD @context if none available).

+

If the target MIME type is "application/geo+json" and the +notification.endpoint.receiverInfo contains a key "Prefer" whose value is set to "body=ld+json" or the "Prefer" key is omitted or +notification.endpoint.receiverInfo does not exist, then the HTTP +notification request includes an @context element in the payload +body.

+

6.3.9 Csource Notification +behaviour

+

In the HTTP binding a csource notification that is triggered by a +csource subscription shall be sent by issuing an HTTP POST request +targeted to the value of notification.endpoint.uri member of the +csource subscription structure (defined by clauses 5.2.12 +and 5.2.14). +The MIME type associated to the POST request shall be "application/json" by default. However, this +can be changed to "application/ld+json" by means of the endpoint.accept +member.

+

If the target MIME type is "application/json" then the HTTP notification +request shall include a Link header with a reference to the +corresponding JSON-LD @context as mandated by the JSON-LD +specification [2], +section 6.2 (to the default JSON-LD @context if none +available).

+

If the optional array (of KeyValuePair type, as defined by clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new custom HTTP Header for each member +named "key" of the key, value pairs that make up the array shall be +generated and included in the HTTP POST's list of headers. The content +of each custom header shall be set equal the content of the +corresponding "value" member of the KeyValuePair. "Key" and +"value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

6.3.10 Pagination behaviour

+

For HTTP operations corresponding to the operations listed in clause +4.12 (see Table +6.2‑1 for a list of HTTP operations with their corresponding +clauses), implementations shall support the HTTP query parameter +specified in Table +6.3.10‑1.

+
+Table 6.3.10-1: Pagination: limit parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Integer +
+0..1 +
+Only values greater or equal to 0. +
+
+It defines the limit to the number of NGSI-LD Elements that shall be +retrieved at a maximum as mandated by clause +5.5.9. The value 0 is only allowed in combination with the +count URI parameter. +
+

This clause defines the specific HTTP binding mechanisms that shall +be used in conjunction with the behaviours defined by clause +5.5.9. Particularly, to flag the existence of related pages that +could be retrieved when dealing with query operations involving +pagination, NGSI-LD Systems implementing the HTTP binding shall use the +HTTP Link header field as mandated by IETF RFC 8288 [7], clause +3, as follows:

+
    +
  • +The pointers to the next and previous pages (when needed as mandated by +clause +5.5.9) shall be serialized as link-value elements. The content of +such link-value(s) shall be: +
    • +
+
    +
  • +For the next page, the Link Target shall be a URI-reference that could +be dereferenced by an NGSI-LD Client to retrieve the next page of +NGSI-LD Elements. In addition, the Link Relation Type shall be equal to +"next", registered under the IANA +Registry of Link Relation Types [20]. +
    • +
  • +For the previous page, the Link Target shall be a URI-reference that +could be dereferenced by an NGSI-LD Client to retrieve the previous page +of NGSI-LD Elements. In addition, the Link Relation Type shall be equal +to "prev", registered under the IANA +Registry of Link Relation Types [20]. +
    • +
+
    +
  • +At least, the "type" Link Target Attribute shall be included by the +previously described serialized Link Header, as mandated by IETF RFC +8288 [7], , and its +value shall be exactly equal to the media type resulting from the +original request made by the NGSI-LD Client (the request that triggered +the current pagination iteration). +
    • +
+
+EXAMPLE: If the media type requested originally was "application/json" then during the entire +pagination iteration the value of the Link Target Attribute "type" shall +be "application/json". +
+

Temporal representation of resources adds an additional dimension to +the pagination. Depending on the requested time range, the response will +contain multiple instances of the requested Attribute, and therefore an +additional pagination mechanism for those temporal representations is +required, in order to limit the time range of the response. If no limits +are specified, a default limit is enforced, depending on implementation +specific configurations. For HTTP operations on Temporal +Evolutionof Entities, implementations shall use the +Partial Content Response (206) as specified by IETF RFC 7233 [31], clause +4.1, if the implementation is not able to respond with the full +representation at once. In this case, for requests where the parameter +lastN is present, pagination shall happen "backwards" (from the +most recent to the least recent timestamp in the requested time range). +For requests without the parameter lastN, pagination shall happen +"forwards" (from the least recent to the most recent timestamp in the +requested time range).

+

This is achieved by including the "Content-Range" header field with the following +contents:

+
    +
  • +"unit" shall be equal to "DateTime"; +
    • +
  • +"range-start" and "range-end" shall be of type DateTime. +They depend on the requested time relationship timerel (as +defined by clause +4.11), as follows: +
    • +
+
    +
  • +If the lastN parameter is present, pagination shall happen +"backwards": +
    • +
+
    +
  • +"range-start" shall be equal to "timeAt" for requests with +timerel=before, "endTimeAt" for +requests with timerel=between, or the most recent timestamp in +the range of the response, for requests with timerel=after; +
    • +
  • +"range-end" shall be equal to the least +recent timestamp in the range of the response; +
    • +
  • +"size" shall be equal to the requested +lastN. +
    • +
+
    +
  • +If the lastN parameter is not present, +pagination shall happen "forwards": +
    • +
+
    +
  • +"range-start" shall be equal to +timeAt for requests with timerel=after or +timerel=between, or the least recent timestamp in the range of +the response, for requests with timerel=before; +
    • +
  • +"range-end" shall be equal to the most +recent timestamp in the range of the response; +
    • +
  • +"size" shall be equal to "*". +
    • +
+

6.3.11 Including +system generated Temporal Attributes

+

For HTTP GET operations performed over the resources /entities/, +/subscriptions/, /csourceRegistrations/, /csourceSubscriptions/ and all +of its sub-resources, implementations shall support the parameter +specified in Table +6.3.11‑1. Implementations shall not raise an error if they do not +hold system generated temporal attributes.

+
+Table 6.3.11-1: Including system generated temporal attributes: options +parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+options +
+Comma separated list of strings +
+0..1 +
+When its value includes the keyword "sysAttrs", a representation of NGSI-LD +Elements shall be provided so that the system generated temporal +attributes createdAt, modifiedAt are included in the +response payload body where known. In the case of temporal +representations, also the system generated temporal attribute +deletedAt is included, if the NGSI-LD Element has been deleted. +
+

6.3.12 Simplified +or aggregated temporal representation of Entities

+

For HTTP GET operations performed over the resource +/temporal/entities/ and all of its sub-resources, implementations shall +support the parameter specified in Table +6.3.12‑1.

+
+Table 6.3.12-1: Temporal Entity representations: format + options +parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+It shall be one of: "temporalValues", +"aggregatedValues". +
+
+ +
+
+When its value is "temporalValues", a +simplified temporal representation of entities shall be provided as +defined by clause +4.5.8. +
+
+ +
+
+When its value is "aggregatedValues", an +aggregated temporal representation of entities shall be provided as +defined by clause +4.5.19. +
+
+ +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword "temporalValues", a simplified temporal +representation of entities shall be provided as defined by clause +4.5.8. +
+
+ +
+
+When its value includes the keyword "aggregatedValues", an aggregated temporal +representation of entities shall be provided as defined by clause +4.5.19. +
+
+ +
+
+Only one of the two keywords can be present in the values of the +parameter. +
+
+ +
+
+If both format and options are present, the value of the +format parameter shall take precedence. +
+

6.3.13 Counting number of results

+

This clause implements the behaviour described in clause +4.13, in case of HTTP binding.

+

For HTTP operations corresponding to the operations listed in clause +4.12 (see Table +6.2‑1 for a list of HTTP operations with their corresponding +clauses), implementations shall support the HTTP query parameter +specified in Table +6.3.13‑1.

+
+Table 6.3.13-1: Counting number of results: count parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+count +
+Boolean +
+0..1 +
+If true, then a special HTTP header (NGSILD-Results-Count) is set +in the response. Regardless of how many entities are actually returned +(maybe due to the limit URI parameter), the total number of +matching results (e.g. number of Entities) is returned. +
+

This clause defines the specific HTTP binding mechanisms that can be +useful to plan the limit and offset URI parameters for +pagination, thus allowing to convey an overview of the number of +entities in a system.

+

To get only the count itself, and no entities, the URI parameter +limit may have the value "0", and +an empty array shall be returned as payload body.

+

Setting the URI parameter limit to zero without including the +count URI parameter will result in a 400 BadRequest +error.

+

6.3.14 Tenant +specification

+

If the system implementing the NGSI-LD API supports multi-tenancy as +described in clause +4.14 and clause +5.5.10, the Tenant, to which the +NGSI-LD HTTP operation is targeted, is specified as the HTTP header +"NGSILD-Tenant", +whose value is the String identifying the Tenant. In case the target Tenant is the default Tenant, the HTTP header is omitted. If the +HTTP header "NGSILD-Tenant" is +present in the HTTP request, it shall also be present in HTTP response. +This also applies to HTTP notifications sent as a result of +subscriptions with an "NGSILD-Tenant" HTTP +header (clause +6.3.8).

+

6.3.15 GeoJSON +representation of spatially bound entities

+

For HTTP GET operations performed over the resource /entities and +/entities/{entity-id}, if the GeoJSON Accept header ("application/geo+json") is present, +implementations shall render the entities of the response in the GeoJSON +format, as described in clause +5.2.29.

+

For GeoJSON representations, a GeoProperty may be selected as +the geolocation to be used as the geometry within the GeoJSON payload. +If no geometryProperty parameter is specified then the +location GeoProperty of the Entity is used.

+
+Table 6.3.15-1: Selecting a geometry +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+geometryProperty +
+String +
+0..1 +
+If not present, "location" is used. +
+datasetId +
+String +
+0..1 +
+Shall be valid URI. If the referenced GeoProperty consists of an +attribute with multiple instances the datasetId specifies which +instance of the value is to be selected. If not present, the default +instance is used. +
+

6.3.16 Expiration time for +cached @contexts

+

Implementations shall comply with the Expires header field (section +5.3 of IETF RFC 7234 [30]) or a max-age or s-maxage +response directive of Cache-Control header field (section 5.2.2 of IETF +RFC 7234 [30]) that +may be present in the downloaded @context. This means that +implementations shall periodically invalidate the "Cached" @contexts according to the +headers mentioned above. Since origin servers do not always provide +explicit expiration times, implementations should assign a heuristic +(for instance according to IETF RFC 7234 [30] section 4.2.2) expiration +time when an explicit time is not specified.

+

6.3.17 Distributed +Operations Caching and Timeout Behaviour

+

The caching of response data received from forwarded HTTP GET +requests is optionally supported by Context +Brokers. For HTTP GET operations performed over the resources +/entities and /entities/{entity-id}, where a Context Source Registration matches the +request and a previous forwarded response has been cached and a +subsequent request occurs before the Context +Source Registration cacheDuration (as defined in Table +5.2.34‑1) has been reached, the result may incorporate data cached +from a previous response. To indicate that +data from a cache has been included in the response, the HTTP header +"NGSILD-Warning" shall be included. The +value shall match the IANA Warning Code [32] 110 – Response is +Stale.

+

"NGSILD-Warning" HTTP headers shall +also be used to indicate instances of abnormal behaviour for distributed +HTTP GET operations performed over the resources /entities and +/entities/{entity-id}.

+
+Table 6.3.17-1: NGSILD Warning Codes +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+IANA Warning Code +
+Remarks +
+110 – Response is Stale +
+No request was made to a specified registration endpoint – data from a +cached value has been reused and it has been incorporated into the +response. +
+111 – Revalidation Failed +
+Although data was received from the registration endpoint within the +specified timeout period, the payload of the response was invalid. This +could occur if the payload was corrupted or a non-NGSI payload was +received. +
+199 – Miscellaneous Warning +
+No response was received from the registration endpoint within the +specified timeout period. +
+299 – Miscellaneous Persistent Warning +
+An error response (such as 403 – Forbidden) was +received from the registration endpoint within the specified timeout +period. This could occur if the Context +Broker has insufficient access rights to retrieve the data. +
+

For distributed HTTP GET operations, registered context sources +should always respond with a valid NGSI-LD payload. The Context Broker shall successfully parse +this data and invalid non-NGSI-LD payloads shall be rejected and not +incorporated into the overall response. It should be noted that a +registration endpoint responding with no data and the HTTP status code +404 – Not Found should not be considered as abnormal +behaviour for distributed operations.

+

For all other operations, which correspond to HTTP Unsafe methods, +the error response should be as informative as possible.

+

In the case of an exclusive or +redirect registration, where all of the data is held +outside of the Context Broker and +held in a single registered source:

+
    +
  • +504 Gateway Timeout – if the single registered source fails to respond +in time. +
    • +
  • +404 Not Found – if resources not found within the single registered +source. +
    • +
  • +502 Bad Gateway – if the single forwarded request fails for any other +reason such as the Context Broker +itself having insufficient access rights. +
    • +
+

In the case of an inclusive or +redirect registration, where an entity is distributed +over multiple equally valid endpoints, but when updating the state of +the distributed entity, an error response is returned from one or more +registered sources:

+
    +
  • +207 Multi Status +
    • +
+

In the case of an auxiliary registration HTTP unsafe +methods are not supported.

+

Whenever failures or timeouts occur, Context Brokers may optionally decline to +make subsequent requests to the same registration endpoint until the +cooldown period (as defined in +Table 5.2.9-1) has been reached.

+

6.3.18 Limiting Distributed +Operations

+

The parameter described in this clause limits the execution of an +operation to a local Context Source or Context Broker (clause +5.5.13). It amends the matching Context +Source Registrations behaviour as described in , in the case of +the HTTP binding in order to avoid cascading distributed operations (see +clause +4.3.6.4). For all operations the resources /entities/, /types/, +/attributes/, /entityOperations/, /temporal/entities/ and +temporal/entityOperations/ (and their respective child resources) +implementations shall support the HTTP query parameter specified in Table 6.3.18‑1. +The Registry API operations are always local and thus are not included +here.

+
+Table 6.3.18-1: Limiting distributed operations: local parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+local +
+Boolean +
+0..1 +
+If local=true then no Context Source +Registrations shall be considered as matching to avoid cascading +distributed operations (see clause +4.3.6.4) +
+
+ +
+

Furthermore, to avoid infinite loops, for all operations, the +resources /entities/, /types/, /attributes/, /subscriptions/, +/csourceSubscriptions/, /entityOperations/, /temporal/entities/ and +temporal/entityOperations/ implementations shall fully support the HTTP +Via Header (IETF RFC 7230 [27]) as specified in table 6.3.18‑2. +AnyContext Broker implementation +passing a distributed operation request onward to another Context Source shall send an additional +field value on the Via header field using its own unique Context Source hostAlias (see clause +5.2.40) as the pseudonym.

+
+Table 6.3.18-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+Via +
+String as defined in IETF RFC 7230 [27] +
+0..1 +
+If present, the listing of previously encountered Context Sources supplied is used when +determining matching registrations +
+

6.3.19 Extra +information to provide when contacting Context Source

+

As specified in clauses 4.3.6.5 +and 4.3.6.6, +extra information to be provided when contacting a Context Source can be specified in the +optional array (of KeyValuePair type, as defined by clause +5.2.22) contextSourceInfo of the CSourceRegistration.

+

In the HTTP binding, if the "jsonldContext" key is present, the URL value +is placed in an HTTP Link Header as described by the JSON-LD +specification [2], +section 6.2 and, whenever a payload body is present in the request, the +HTTP Content-Type Header is set to "application/json". For all other keys, a new +custom HTTP header is added for each member named "key" of the key-value +pairs that make up the array shall be generated and included in the HTTP +list of headers. The content of each custom header shall be set equal to +the content of the corresponding "value" member of the +KeyValuePair, unless the special value "urn:ngsi-ld:request" has been set, in which +case the value is to be taken from the triggering request, if present +there. "Key" and "value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer +Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning +HTTP headers.

+

Headers derived from other elements of the CSourceRegistration, e.g. +"NGSILD-Tenant", +take precedence and cannot be overridden using contextSourceInfo. +The same applies for headers generally set by HTTP itself, e.g. +Content-length.

+

6.3.20 Invalid +parameters

+

If an HTTP request for an operation contains parameters that are +incompatible with the operation, or it contains values of the +options parameter that are not supported by the operation, an +HTTP error response of type InvalidRequest should be +returned.

+

6.4 Resource: +entities/

+

6.4.1 Description

+

This resource represents the entities known to an NGSI-LD system.

+

6.4.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/ +
    • +
+

6.4.3 Resource +methods

+

6.4.3.1 POST

+

This method is bound to the operation "Create Entity" and shall +exhibit the behaviour defined by clause +5.6.1, taking the entity to be created from the HTTP request payload +body. Figure +6.4.3.1‑1 shows the Create Entity interaction and Table 6.4.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.4.3.1-1: Create Entity interaction +
+
+Table 6.4.3.1-1: Post Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the entity that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +member should convey more information about the error. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the entity or an exclusive or redirect +registration defining the entity already exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable Entity +
+It is used to indicate that the operation is not available, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.4.3.2 GET

+

This method is associated to the operation "Query Entities" and shall +exhibit the behaviour defined by clause +5.7.2, providing entities as part of the HTTP response payload body. +In addition to this method, an alternative way to perform "Query +Entities" operations via POST is defined in clause +6.23. Figure 6.4.3.2‑1 shows the +query entities interaction.

+
+ +
+
+Figure 6.4.3.2‑1: Query Entities +interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.4.3.2‑1, +the request headers that shall be supported by implementations are those +defined in Table +6.4.3.2‑2 and Table 6.4.3.2‑3 +describes the request body and possible responses.

+
+Table 6.4.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved. +
+type +
+String +

0..1

+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Selection of Entity Types as per clause +4.17. “*” is +also allowed as a value and local is implicitly set to +true and shall not be explicitly set tofalse. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids. +
+attrs +
+Comma separated list of strings +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be matched by the Entities and also included in +the response, i.e. only Entities that contain at least one of the +Attributes in attrs are to be included in the response, and only +the Attributes listed in attrs are to be included in each of the +Entities of the response. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or a projected Attribute name) +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or a projected Attribute name) +
+
+When defined, the listed Entity members are removed from each Entity +within the payload +
+q +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present, unless the execution of the request is +limited to local scope (see clause +5.5.13). +
+Query as per clause +4.9. +
+expandValues +
+Comma separated list of strings +
+0..1 +
+
+ +
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes whose values shall be expanded into URIs according to +the supplied @context prior to executing a query. It is part of +query +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9. +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present. At +least one among: type, attrs, q, or geometry +shall be present, unless the execution of the request is limited to +local scope (see clause +5.5.13). +
+Geometry as per clause +4.10. It is part of geoquery. +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present. +
+Geo relationship as per clause +4.10. It is part of geoquery. +
+coordinates +
+String +
+0..1 +
+
+It shall be one if geometry or georel are present. +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery. +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored unless a geoquery is present. +
+It represents the name of the Property that contains the +geospatial data that will be used to resolve the geoquery. By default, +will be location (see clause +4.7). +
+geometryProperty +
+String +
+0..1 +
+It represents a Property name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the toplevel geometry field. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19). +
+containedBy +
+Comma separated list of URIs +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. Only applicable if joinLevel is +present +
+join +
+String +
+0..1 +
+The type of Linked Entity retrieval +to apply (see clause +4.5.23). Allowed values: "flat", +"inline", "@none" +
+joinLevel +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. +
+
+Only applicable if join parameter is present +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" for including the default Attribute +instances. Specifies the datasetIds of the Attribute instances to be +selected for each matched Attribute as per clause +4.5.5. +
+entityMap +
+Boolean +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response +
+
+Table 6.4.3.2-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+NGSILD-EntityMap +
+URI +
+0..1 +
+If present, the EntityMap supplied is used for determining the set of +Entities requested during the query operation. The location of the +EntityMap used in the query operation is returned in the response +
+
+Table 6.4.3.2-3: Get Entities request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity[] +
+1 +
+200 OK +
+A response body containing the query result as a list of entities, +unless the Accept Header indicates that the Entities are to be rendered +as GeoJSON. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that contains the resource URI of +the EntityMap resource used in the operation. +
+GeoJSON FeatureCollection +
+1 +
+200 OK +
+If the Accept Header indicates that the Entities are to be rendered as +GeoJSON, a response body containing the query result as GeoJSON +FeatureCollection is returned. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that contains the resource URI of +the EntityMap resource used in the operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+ +
+
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Registered Context +Sources to indicate that the data format of the request is +unsupported see clause +6.3.7. +
+

6.5 Resource: +entities/{entityId}

+

6.5.1 Description

+

This resource represents an entity known to an NGSI-LD system.

+

6.5.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.5.2‑1.

+
+Table 6.5.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the entity to be retrieved +
+

6.5.3 Resource +methods

+

6.5.3.1 GET

+

This method is associated to the operation "Retrieve Entity" and +shall exhibit the behaviour defined by clause +5.7.1. The Entity identifier is the value of the resource URI +variable "entityId". Figure 6.5.3.1‑1 +shows the retrieve entity interaction.

+
+ +
+
+Figure 6.5.3.1-1: Retrieve Entity interaction +
+

The query parameters that shall be supported are those defined in table 6.5.3.1‑1, +the request headers that shall be supported by implementations are those +defined in table +6.5.3.1‑2 and table 6.5.3.1‑3 +describes the request body and possible responses.

+
+Table 6.5.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+attrs +
+Comma separated list of strings +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be matched by the Entity and included in the +response. If the Entity does not have any of the Attributes in +attrs, then a 404 Not Found shall be retrieved. If +attrs is not specified, no matching is performed and all +Attributes related to the Entity shall be retrieved. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or a projected Attribute name). When +defined, every Entity within the payload body is reduced down to only +contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or a projected Attribute name). When +defined, the listed Entity members are removed from each Entity within +the payload +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+geometryProperty +
+String +
+0..1 +
+It represents a GeoProperty name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the "geometry" element. By default, it +shall be location. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+containedBy +
+Comma separated list of URIs +
+0..1 +
+List of entity ids which have previously been encountered whilst +retrieving the Entity Graph. Only applicable if joinLevel is +present +
+join +
+String +
+0..1 +
+The type of Linked Entity retrieval +to apply (see clause +4.5.23). Allowed values: "flat", +"inline", "@none" +
+joinLevel +
+Positive Integer +
+0..1 +
+Depth of Linked Entity retrieval to +apply. Default is 1 +
+
+Only applicable if join parameter is: "flat" or "inline". +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+entityMap +
+Boolean +
+0..1 +
+If true, the location of the EntityMap used in the operation is +returned in the response +
+
+Table 6.5.3.1-2: Request Headers +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+NGSILD-EntityMap +
+URI +
+0..1 +
+If present, the EntityMap supplied is used for determining the extent of +the Entity data requested during the retrieval operation. The location +of the EntityMap used in the retreieval operation is returned in the +response +
+
+Table 6.5.3.1-3: Get Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +entity containing the selected Attributes, unless the Accept Header +indicates that the Entity is to be rendered as GeoJSON. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that contains the resource URI of +the EntityMap resource used in the operation. +
+GeoJSON Feature +
+1 +
+200 OK +
+If the Accept Header indicates that the Entity is to be rendered as +GeoJSON, a GeoJSON Feature is returned. +
+
+ +
+
+If an EntityMap has been requested, the HTTP response shall include an +"NGSILD-EntityMap" HTTP header that contains the resource URI of +the EntityMap resource used in the operation. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Registered Context +Sources to indicate that the data format of the request is +unsupported see clause +6.3.7. +
+

6.5.3.2 DELETE

+

This method is associated to the operation "Delete Entity" and shall +exhibit the behaviour defined by . The Entity identifier is the value of +the resource URI variable "entityId". Figure 6.5.3.2‑1 +shows the delete entity interaction.

+
+ +
+
+Figure 6.5.3.2-1: Delete Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.2‑1 +and Table +6.5.3.2‑2 describes the request body and possible responses.

+
+Table 6.5.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.5.3.2-2: Delete Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.5.3.3 PUT

+

This method is bound to the "Replace Entity" operation and shall +exhibit the behaviour defined by clause +5.6.18. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.5.3.3‑1 +shows the Replace Entity interaction.

+
+ +
+
+Figure 6.5.3.3-1: Replace Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.3‑1 +and Table +6.5.3.3‑2 describes the request body and possible responses.

+
+Table 6.5.3.3-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.5.3.3-2: Replace Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Entity to be +replaced. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+The entity was replaced successfully. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

6.5.3.4 PATCH

+

This method is bound to the "Merge Entity" operation and shall +exhibit the behaviour defined by clause +5.6.17. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.5.3.4‑1 +shows the Merge Entity interaction.

+
+ +
+
+Figure 6.5.3.4-1: Merge Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.5.3.4‑1 +and Table +6.5.3.4‑2 describes the request body and possible responses.

+
+Table 6.5.3.4-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+format +
+String +
+0..1 +
+It shall be one of: "simplified" (or its +synonym "keyValues"). Where present it +indicates that a simplified representation of Entities has been provided +as defined by clause +4.5.4 +
+
+ +
+
+In this case, when a merge operation applies to an existing Attribute +the type field of the Attribute shall remain unchanged (any +attempt to modify the type of an +
+
+Attribute shall result in a BadRequest error). +
+options +
+Comma separated list of strings +
+0..1 +
+An alternative mechanism to include the format parameter. +Deprecated +
+
+ +
+
+When its value includes the keyword"simplified" (or +its synonym "keyValues"), this indicates +that a simplified representation of Entities has been provided as +defined by clause +4.5.4. +
+
+ +
+
+If both format and options are present, the value of the +format parameter shall take precedence. +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+observedAt +
+String +
+0..1 +
+It shall be a DateTime (see clause +4.6.3). +
+
+When a merge operation applies to a pre-existing Attribute which +previously contained an observedAt sub-attribute, the value held +in this query parameter shall be used if no specific observedAt +sub-Attribute is found in the payload body. +
+lang +
+String +
+0..1 +
+It represents the natural language of data held in the request. +
+
+When a merge operation applies to a pre-existing LanguageProperty +and the value is supplied as a string or string array in the payload +body, this query parameter shall be used to determine the key within the +languageMap JSON Object to update. +
+
+Table 6.5.3.4-2: Merge Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be merged. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were merged successfully. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

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

+

6.6.1 Description

+

This resource represents all the Attributes (Properties or +Relationships) of an NGSI-LD Entity.

+

6.6.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId}/attrs +
    • +
+

Resource URI variables for this resource are defined in Table 6.6.2‑1.

+
+Table 6.6.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+

6.6.3 Resource +methods

+

6.6.3.1 POST

+

This method is bound to the "Append Attributes" operation and shall +exhibit the behaviour defined by clause +5.6.3. The Entity identifier is the value of the resource URI +variable "entityId". The data to be appended shall be contained in the +HTTP request payload body. Figure 6.6.3.1‑1 +shows the Append Attributes interaction.

+
+ +
+
+Figure 6.6.3.1-1: Append Attributes interaction +
+

The query parameters that shall be supported are those defined in Table 6.6.3.1‑1 +and Table +6.6.3.1‑2 describes the request body and possible responses.

+
+Table 6.6.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+options +
+Comma separated list of strings +
+0..1 +
+“noOverwrite" indicates that no attribute +overwrite shall be performed. +
+
+ +
+
+ +
+
+Table 6.6.3.1-2: Post Attributes request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be added. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were appended successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+Only the Attributes included in the response payload body were +successfully appended. +
+
+ +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.6.3.2 PATCH

+

This method is bound to the "Update Attributes" operation and shall +exhibit the behaviour defined by clause +5.6.2. The Entity identifier is the value of the resource URI +variable "entityId". The data to be updated shall be contained in the +HTTP request payload body. Figure 6.6.3.2‑1 +shows the Update Attributes interaction.

+
+ +
+
+Figure 6.6.3.2-1: Update Attributes interaction +
+

The query parameters that shall be supported are those defined in Table 6.6.3.2‑1 +and Table +6.6.3.2‑2 describes the request body and possible responses.

+
+Table 6.6.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.6.3.2-2: Patch Attributes request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing a complete representation of the Attributes +to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were updated successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+Only the Attributes included in the response payload body were +successfully updated. If no Attributes were successfully updated the +updated array of UpdateResult (see clause +5.2.18) will be empty. +
+
+ +
+
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier not known to the +system, see clause 6.3.2. +
+

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

+

6.7.1 Description

+

This resource represents an attribute (Property or Relationship) of +an NGSI-LD Entity.

+

6.7.2 Resource +definition

+

Resource URI:

+
    +
  • +/entities/{entityId}/attrs/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.7.2‑1.

+
+Table 6.7.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+

6.7.3 Resource +methods

+

6.7.3.1 PATCH

+

This method is bound to the "Partial Attribute Update" operation and +shall exhibit the behaviour defined by clause +5.6.4. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". The Entity Fragment shall be contained in the HTTP +request payload body. Figure 6.7.3.1‑1 +shows the Partial Attribute Update interaction.

+
+ +
+
+Figure 6.7.3.1-1: Partial Attribute Update interaction +
+

The query parameters that shall be supported are those defined in Table 6.7.3.1‑1 +and Table +6.7.3.2‑2 describes the request body and possible responses.

+
+Table 6.7.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.7.3.1-2: Partial Attribute Update request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity Fragment +
+1 +
+Entity Fragment containing the elements of the attribute to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The attribute was updated successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier or attribute name +not known to the system, see clause 6.3.2. +
+

6.7.3.2 DELETE

+

This method is associated to the operation "Delete Attribute" and +shall exhibit the behaviour defined by clause +5.6.5. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". Figure 6.7.3.2‑1 +shows the Delete Attribute interaction, Table 6.7.3.2‑1 +shows the delete parameters to be supported and Table 6.7.3.2‑2 +describes the request body and possible responses.

+
+ +
+
+Figure 6.7.3.2-1: Delete Attribute interaction +
+
+Table 6.7.3.2-1: Delete parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+deleteAll +
+Boolean +
+0..1 +
+If true, all attribute instances are deleted. Otherwise (default) +only the Attribute instance specified by the datasetId is +deleted. In case neither the deleteAll flag nor a datasetId is +present, the default Attribute instance is deleted. +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+datasetId +
+String +
+0..1 +
+Shall be a valid URI. Specifies the datasetId of the dataset to +be deleted. +
+
+Table 6.7.3.2-2: Delete Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) or +attribute name not known to the system. see clause 6.3.2. +
+

6.7.3.3 PUT

+

This method is bound to the "Replace Attribute" operation and shall +exhibit the behaviour defined by clause +5.6.19. The Entity identifier is the value of the resource URI +variable "entityId". The attribute name is the value of the resource URI +variable "attrId". The Attribute Fragment shall be contained in the HTTP +request payload body. Figure 6.7.3.3‑1 +shows the Replace Attribute interaction.

+
+ +
+
+Figure 6.7.3.3-1: Replace Attribute interaction +
+

The query parameters that shall be supported are those defined in Table 6.7.3.3‑1 +and Table +6.7.3.3‑2 describes the request body and possible responses.

+
+Table 6.7.3.3-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+type +
+String +
+0..1 +
+Selection of Entity Types as per clause +4.17 +
+
+ +
+
+Table 6.7.3.3-2: Replace Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Attribute Fragment +
+1 +
+Attribute Fragment replacing the previous data. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The attribute was replaced successfully. +
+UpdateResult +
+1 +
+207 Multi-Status +
+If the entity input data matches to a registration, the relevant parts +of the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a UpdateResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier or attribute name +not known to the system, see clause 6.3.2. +
+

6.8 Resource: +csourceRegistrations/

+

6.8.1 Description

+

This resource represents the context source registrations known to an +NGSI-LD system.

+

6.8.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceRegistrations/ +
    • +
+

6.8.3 Resource +methods

+

6.8.3.1 POST

+

This method is bound to the operation "Register Context Source" and +shall exhibit the behaviour defined by clause +5.9.2, taking the context source registration to be created from the +HTTP request payload body. Figure 6.8.3.1‑1 +shows the Register Context Source interaction and Table 6.8.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.8.3.1-1: Register Context Source interaction +
+
+Table 6.8.3.1-1: Patch Attribute request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+CSourceRegistration +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created context source registration resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the context source registration already +exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable +
+
+Context Source Registration +
+It is used to indicate that the operation is not available see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.8.3.2 GET

+

This method is associated to the operation "Query Context Source +Registrations" and shall exhibit the behaviour defined by clause +5.10.2, i.e. the parameters in the request describe entity related +information, but instead of directly providing this entity information, +the context source registration data, which describes context sources +that can possibly provide the information, are returned as part of the +HTTP response payload body. Figure 6.8.3.2‑1 +shows the Query Context Source Registrations interaction.

+
+ +
+
+Figure 6.8.3.2-1: Query Context Source Registrations interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.8.3.2‑1 +and Table +6.8.3.2‑2 describes the request body and possible responses.

+
+Table 6.8.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved +
+type +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Selection of Entity Types as per clause +4.17 +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids satisfying the +query +
+attrs +
+Comma separated list strings +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes (Properties or Relationships) to be retrieved +
+q +
+String +
+0..1 +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Query as per clause +4.9 +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9 +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present. +
+
+At least one among: type, attrs, q, or +georel shall be present. +
+Geometry as per clause +4.10. It is part of geoquery +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present. +
+Geo relationship as per clause +4.10. It is part of geoquery +
+coordinates +
+String +
+0..1 +
+
+It shall be one if geometry or georel are present. +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored if no geoquery is present. +
+It represents the name of the Property that contains the geospatial data +that will be used to resolve the geoquery +
+timeproperty +
+String +
+0..1 +
+
+It shall be ignored if no temporal query is present. +
+It represents a Temporal Property name. +
+
+ +
+
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8) +
+timerel +
+String +
+0..1 +
+It represents the temporal relationship as defined by clause +4.1. +
+
+ +
+
+Allowed values: "before", "after", "between" +
+timeAt +
+String +
+0..1 +
+It represents the timeAt parameter as defined by clause +4.1. +
+
+ +
+
+It shall be a DateTime. Cardinality shall be 1 if timerel +is present +
+endTimeAt +
+String +
+0..1 +
+It represents the endTimeAt parameter as defined by clause +4.1. +
+
+ +
+
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between" +
+geometryProperty +
+String +
+0..1 +
+It represents a Property name. +
+
+ +
+
+In the case of GeoJSON Entity representation, this parameter indicates +which GeoProperty to use for the toplevel geometry field +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response. +
+
+ +
+
+It is used to reduce languageMaps to a string or string array +property in a single preferred language +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19) +
+
+Table 6.8.3.2-2: Get Context Source Registrations request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+CSourceRegistration[] +
+1 +
+200 OK +
+A response body containing the query result as an array of context +source registrations. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.9 Resource: +csourceRegistrations/{registrationId}

+

6.9.1 Description

+

This resource represents the context source registration, identified +by registrationId, known to an NGSI-LD system.

+

6.9.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceRegistrations/{registrationId} +
    • +
+

Resource URI variables for this resource are defined in Table 6.9.2‑1.

+
+Table 6.9.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+registrationId +
+Id (URI) of the context source registration +
+

6.9.3 Resource +methods

+

6.9.3.1 GET

+

This method is associated with the operation "Retrieve Context Source +Registration" and shall exhibit the behaviour defined by clause +5.10.1. The registration identifier is the value of the resource URI +variable "registrationId". Figure 6.9.3.1‑1 +shows the Retrieve Context Source Registration interaction and Table 6.9.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.1-1: Retrieve Context Source Registration interaction +
+
+Table 6.9.3.1-1: Get Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+CSourceRegistration +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +context source registration. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier (URI) not known to the system, see clause 6.3.2. +
+

6.9.3.2 PATCH

+

This method is bound to the "Update Context Source Registration" +operation and shall exhibit the behaviour defined by clause +5.9.3. The context source registration identifier is the value of +the resource URI variable "registrationId". The context source +registration to be updated shall be contained in the HTTP request +payload body. Figure 6.9.3.2‑1 +shows the Update Context Source Registration interaction and Table 6.9.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.2-1: Update Context Source Registration interaction +
+
+Table 6.9.3.2-1: Patch Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+CSourceRegistration Fragment +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration that is to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+The context source registration was successfully updated. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier not known to the system, see clause 6.3.2. +
+

6.9.3.3 DELETE

+

This method is associated to the operation "Delete Context Source +Registration" and shall exhibit the behaviour defined by clause +5.9.4. The context source registration identifier is the value of +the resource URI variable "registrationId". Figure 6.9.3.3‑1 +shows the Delete Context Source Registration interaction and Table 6.9.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.9.3.3-1: Delete Context Source Registration interaction +
+
+Table 6.9.3.3-1: Delete Context Source Registration request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a context source registration +identifier (URI) not known to the system, see clause 6.3.2. +
+

6.10 Resource: +subscriptions/

+

6.10.1 Description

+

This resource represents the subscriptions known to an NGSI-LD +system.

+

6.10.2 Resource +definition

+

Resource URI:

+
    +
  • +/subscriptions/ +
    • +
+

6.10.3 Resource +methods

+

6.10.3.1 POST

+

This method is bound to the operation "Create Subscription" and shall +exhibit the behaviour defined by clause +5.8.1, taking the subscription to be created from the HTTP request +payload body. Figure +6.10.3.1‑1 shows the Create Subscription interaction and Table 6.10.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.10.3.1-1: Create Subscription interaction +
+
+Table 6.10.3.1-1: Post Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the subscription that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created subscription resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the subscription already exists see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.10.3.2 GET

+

This method is associated to the operation "Query Subscriptions" and +shall exhibit the behaviour defined by clause +5.8.4, providing the subscription data as part of the HTTP response +payload body. Figure +6.10.3.2‑1 shows the Query Subscriptions interaction.

+
+ +
+
+Figure 6.10.3.2-1: Query Subscriptions interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.10.3.2‑1 +and Table +6.10.3.2‑2 describes the request body and possible responses.

+
+Table 6.10.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Number +
+0..1 +
+Maximum number of subscriptions to be retrieved +
+
+Table 6.10.3.2-2: Get Subscriptions request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription[] +
+1 +
+200 OK +
+A response body containing a list of subscriptions. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.11 Resource: +subscriptions/{subscriptionId}

+

6.11.1 Description

+

This resource represents a subscription known to an NGSI-LD +system.

+

6.11.2 Resource +definition

+

Resource URI:

+
    +
  • +/subscriptions/{subscriptionId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.11.2‑1.

+
+Table 6.11.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+subscriptionId +
+Id (URI) of the concerned subscription +
+

6.11.3 Resource +methods

+

6.11.3.1 GET

+

This method is associated to the operation "Retrieve Subscription" +and shall exhibit the behaviour defined by clause +5.8.3. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.1‑1 shows the Retrieve Subscription interaction and Table 6.11.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.1-1: Retrieve Subscription interaction +
+
+Table 6.11.3.1-1: Get Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +subscription. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.11.3.2 PATCH

+

This method is associated to the operation "Update Subscription" and +shall exhibit the behaviour defined by clause +5.8.2. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.2‑1 shows the Update Subscription interaction and Table 6.11.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.2-1: Update Subscription interaction +
+
+Table 6.11.3.2-1: Patch Subscription request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription Fragment +
+1 +
+Subscription Fragment including id, type and any other subscription +field to be changed +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.11.3.3 DELETE

+

This method is associated to the operation "Delete Subscription" and +shall exhibit the behaviour defined by clause +5.8.5. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.11.3.3‑1 shows the Delete Subscription interaction and Table 6.11.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.11.3.3-1: Delete Subscription interaction +
+
+Table 6.11.3.3-1: Delete Subscription request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.12 Resource: +csourceSubscriptions/

+

6.12.1 Description

+

This resource represents the context source registration +subscriptions known to an NGSI-LD system.

+

6.12.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceSubscriptions/ +
    • +
+

6.12.3 Resource +methods

+

6.12.3.1 POST

+

This method is bound to the operation "Create Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.2, taking the context source registration subscription to be +created from the HTTP request payload body. Figure +6.12.3.1‑1 shows the Create Context Source Registration Subscription +interaction and Table 6.12.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.12.3.1-1: Create Context Source Registration Subscription +interaction +
+
+Table 6.12.3.1-1: Post Context Source Registration Subscription request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration subscription that is to be created. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created context source registration subscription +resource. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+409 Conflict +
+It is used to indicate that the context source registration subscription +already exists, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.12.3.2 GET

+

This method is associated to the operation "Query Context Source +Registration Subscriptions" and shall exhibit the behaviour defined by +clause +5.11.5, providing the context source registration subscription data +as part of the HTTP response payload body. Figure +6.12.3.2‑1 shows the Query Context Source Registration Subscriptions +interaction.

+
+ +
+
+Figure 6.12.3.2-1: Query Context Source Registration Subscriptions +interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.12.3.2‑1 +and Table +6.12.3.2‑2 describes the request body and possible responses.

+
+Table 6.12.3.2-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+limit +
+Number +
+0..1 +
+Maximum number of subscriptions to be retrieved +
+
+Table 6.12.3.2-2: Get Context Source Registration Subscriptions request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription[] +
+1 +
+200 OK +
+A response body containing a list of context source registration +subscriptions. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.13 Resource: +csourceSubscriptions/{subscriptionId}

+

6.13.1 Description

+

This resource represents the context source registration +subscription, identified by subscriptionId, known to an NGSI-LD +system.

+

6.13.2 Resource +definition

+

Resource URI:

+
    +
  • +/csourceSubscriptions/{subscriptionId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.13.2‑1.

+
+Table 6.13.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+subscriptionId +
+Id (URI) of the concerned context source registration subscription +
+

6.13.3 Resource +methods

+

6.13.3.1 GET

+

This method is associated to the operation "Retrieve Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.4. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.1‑1 shows the Retrieve Context Source Registration +interaction and Table 6.13.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription +interaction +
+
+Table 6.13.3.1-1: Get Context Source Registration Subscription request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Subscription +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +context source registration subscription. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.13.3.2 PATCH

+

This method is associated to the operation "Update Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.3. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.2‑1 shows the Update Context Source Registration Subscription +interaction and Table 6.13.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.2-1: Update Context Source Registration Subscription +interaction +
+
+Table 6.13.3.2-1: Patch Context Source Registration Subscription request +body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Subscription Fragment +
+1 +
+Subscription Fragment including id, type and any other context source +registration subscription field to be changed +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.13.3.3 DELETE

+

This method is associated to the operation "Delete Context Source +Registration Subscription" and shall exhibit the behaviour defined by clause +5.11.6. The subscription identifier is the value of the resource URI +variable "subscriptionId". Figure +6.13.3.3‑1 shows the Delete Context Source Registration Subscription +interaction and Table 6.13.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.13.3.3-1: Delete Context Source Registration Subscription +interaction +
+
+Table 6.13.3.3-1: Delete Context Source Registration Subscription +request body
+and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided a subscription identifier (URI) not +known to the system, see clause 6.3.2. +
+

6.14 Resource: +entityOperations/create

+

6.14.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity creation for the NGSI-LD API.

+

6.14.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/create +
    • +
+

6.14.3 Resource +methods

+

6.14.3.1 POST

+

This method is associated to the operation "Batch Entity Creation" +and shall exhibit the behaviour defined by clause +5.6.7. Figure +6.14.3.1‑1 shows the operation interaction and Table 6.14.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.14.3.1-1: Batch Entity Creation Interaction +
+
+Table 6.14.3.1-1: Batch Entity Creation Interaction and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of entities to be created +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+String[] +
+1 +
+201 Created +
+If all entities have been successfully created, an array of Strings +containing URIs is returned in the response. Each URI represents the +Entity ID of a created entity. There is no restriction as to the order +of the Entity IDs. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully created, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully created entities, while the second array +(errors) contains information about the error for each of the +entities that could not be created. There is no restriction as to the +order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.15 Resource: +entityOperations/upsert

+

6.15.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity creation or update for the NGSI-LD +API.

+

6.15.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/upsert +
    • +
+

6.15.3 Resource +methods

+

6.15.3.1 POST

+

This method is associated to the operation "Batch Entity Creation or +Update (Upsert)" and shall exhibit the behaviour defined by clause +5.6.8. Figure +6.15.3.1‑1 shows the operation interaction and Table 6.15.3.1‑1 +describes the request body and possible responses.

+

The options query parameter for this request can take the +following values:

+
    +
  • +"replace". Indicates that all the +existing Entity content shall be replaced (default mode); +
    • +
  • +"update". Indicates that existing Entity +content shall be updated. +
    • +
+
+ +
+
+Figure 6.15.3.1-1: Batch Entity Creation or Update Interaction +
+
+Table 6.15.3.1-1: Batch Entity Creation or Update Interaction and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of entities to be created/updated +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+String[] +
+1 +
+201 Created +
+If all entities not existing prior to this request have been +successfully created and the others have been successfully updated, an +array of String (with the URIs representing the Entity IDs of the +created entities only) is returned in the response. There is no +restriction as to the order of the Entity IDs. The merely updated +entities do not take part in the response (corresponding to 204 No +Content returned in the case of updates). +
+N/A +
+N/A +
+204 No Content +
+If all entities already existed and are successfully updated, there is +no payload body in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully created or +updated, a response body containing the result of each operation +contained in the batch is returned in a BatchOperationResult +structure. It contains two arrays. The first array (success) +contains the URIs of the successfully created or updated entities, while +the second array (errors) contains information about the error +for each of the entities that could not be created or updated. There is +no restriction as to the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.16 Resource: +entityOperations/update

+

6.16.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity update for the NGSI-LD API.

+

6.16.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/update +
    • +
+

6.16.3 Resource +methods

+

6.16.3.1 POST

+

This method is associated to the operation "Batch Entity Update" and +shall exhibit the behaviour defined by clause +5.6.9. Figure +6.16.3.1‑1 shows the operation interaction and Table 6.16.3.1‑1 +describes the request body and possible responses.

+

The options query parameter for this request can take the +following values:

+
    +
  • +"noOverwrite". Indicates that no +attribute overwrite shall be performed. +
    • +
+
+ +
+
+Figure 6.16.3.1-1: Batch Entity Update Interaction +
+
+Table 6.16.3.1-1: Batch Entity Update Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of Entities to be updated +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities have been successfully updated, there is no payload body +in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully updated, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully updated entities, while the second array +(errors) contains information about the error for each of the +entities that could not be updated. There is no restriction as to the +order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.17 Resource: +entityOperations/delete

+

6.17.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity deletion for the NGSI-LD API.

+

6.17.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/delete +
    • +
+

6.17.3 Resource +methods

+

6.17.3.1 POST

+

This method is associated to the operation "Batch Entity Delete" and +shall exhibit the behaviour defined by clause +5.6.10. Figure +6.17.3.1‑1 shows the operation interaction and Table 6.17.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.17.3.1-1: Batch Entity Delete Interaction +
+
+Table 6.17.3.1-1: Batch Entity Delete Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+String[] +
+1 +
+Array of String (URIs representing Entity IDs) to be deleted +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities existed and have been successfully deleted, there is no +payload body in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If some or all of the entities have not been successfully deleted, or +did not exist, a response body containing the result of each operation +contained in the batch is returned in a BatchOperationResult +structure. It contains two arrays. The first array (success) +contains the URIs of the successfully deleted entities, while the second +array (errors) contains information about the error for each of +the entities that could not be deleted. There is no restriction as to +the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.18 Resource: +temporal/entities/

+

6.18.1 Description

+

This resource represents the Temporal +Evolution of Entities known to an NGSI-LD +system.

+

6.18.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/ +
    • +
+

6.18.3 Resource +methods

+

6.18.3.1 POST

+

This method is associated to the operation "Create or Update Temporal +Evolution of an Entity" and shall exhibit the behaviour defined by clause +5.6.11, taking the temporal representation of Entity to be created +from the HTTP request payload body. Figure +6.18.3.1‑1 shows this interaction and Table 6.18.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity +interaction +
+
+Table 6.18.3.1-1: Post EntityTemporal request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the temporal representation of the Entity that is to be created (or +updated). +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+Upon creation success, the HTTP response shall include a "Location" HTTP header that contains the +resource URI of the created entity resource. +
+N/A +
+N/A +
+204 No Content +
+Upon update success. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +member should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable Entity +
+It is used to indicate that the operation is not available, see clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.18.3.2 GET

+

This method is associated to the operation "Query Temporal Evolution +of Entities" and shall exhibit the behaviour defined by clause +5.7.4, providing the Temporal Evolution of the matching Entities as +part of the HTTP response payload body. In addition to this method, an +alternative way to perform "Query Temporal Evolution of Entities" +operations via POST is defined in clause +6.24. Figure +6.18.3.2‑1 shows this interaction.

+
+ +
+
+Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction +
+

The query parameters that shall be supported by implementations are +those defined in Table 6.18.3.2‑1 +and Table +6.18.3.2‑2 describes the request body and possible responses.

+
+Table 6.18.3.2-1: Temporal Evolution Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+id +
+Comma separated list of strings +
+0..1 +
+Each String shall be a valid URI.
+List of entity ids to be retrieved +
+type +
+String +
+0..1 +
+
+It shall be 1 if attrs is not present, unless the execution of +the request is limited to local scope (see clause +5.5.13). +
+Selection of Entity Types as per clause +4.17. “*” is +also allowed as a value and local is implicitly set to +true and shall not be explicitly set tofalse. +
+idPattern +
+Regular expression as defined by [11] +
+0..1 +
+Regular expression that shall be matched by entity ids +
+attrs +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if type is not present, unless the execution of the +request is limited to local scope (see clause +5.5.13). +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes
+(Properties or Relationships) to be retrieved +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or an Attribute name). +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or an Attribute name). +
+
+When defined, the listed Entity members are removed from each Entity +within the payload +
+q +
+String +
+0..1 +
+Query as per clause +4.9 +
+csf +
+String +
+0..1 +
+Context Source filter as per clause +4.9 +
+geometry +
+String +
+0..1 +
+
+It shall be 1 if georel or coordinates are present +
+Geometry as per clause +4.10. It is part of geoquery +
+georel +
+String +
+0..1 +
+
+It shall be 1 if geometry or coordinates are present +
+Geo relationship as per clause +4.10. It is part of geoquery +
+coordinates +
+String +
+0..1 +
+
+It shall be one if georel or geometry are present +
+Coordinates serialized as a string as per clause +4.10. It is part of geoquery +
+geoproperty +
+String +
+0..1 +
+
+It shall be ignored if no geoquery is present +
+The name of the GeoProperty that contains the geospatial data +that will be used to resolve the geoquery. By default, will be +location. (See clause +4.7) +
+timeproperty +
+String +
+0..1 +
+It represents a Temporal Property name.
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8) +
+timerel +
+String +
+1 +
+It represents the temporal relationship as defined by clause +4.11.
+Allowed values: "before", "after", "between" +
+timeAt +
+String +
+1 +
+representing the timeAt parameter as defined by clause +4.11.
+It shall be a DateTime +
+endTimeAt +
+String +
+0..1 +
+It representing the endTimeAt parameter as defined by clause +4.11.
+It shall be a DateTime. Cardinality shall be 1 if timerel +is equal to "between" +
+lastN +
+Positive integer +
+0..1 +
+Only the last n instances, per Attribute, per Entity (under the +specified time interval) shall be retrieved +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response.
+It is used to reduce languageMaps to a string or string array +property in a single preferred language +
+aggrMethods +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if aggregatedValues is present in the +options parameter +
+Each String represents an aggregation method, as defined by clause +4.5.19.
+Only applicable if "aggregatedValues" is present in the options parameter +
+aggrPeriodDuration +
+String +
+0..1 +
+It represents the duration of each period used for the aggregation as +defined by clause +4.5.19.
+If not specified, it defaults to a duration of 0 seconds and is +interpreted as a duration spanning the whole time-range specified by the +temporal query. +
+
+Only applicable if "aggregatedValues" is present in the options +parameter +
+scopeQ +
+String +
+0..1 +
+Scope query (see clause +4.19) +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+
+Table 6.18.3.2-2: Query Entities History request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal[] +
+1 +
+200 OK +
+A response body containing the query result as a list of temporal +representation of Entities. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.19 Resource: +temporal/entities/{entityId}

+

6.19.1 Description

+

This resource is associated to the Temporal +Evolution of an Entity known to an NGSI-LD +system.

+

6.19.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.19.2‑1.

+
+Table 6.19.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the entity to be retrieved +
+

6.19.3 Resource +methods

+

6.19.3.1 GET

+

This method is associated to the operation "Retrieve Temporal +Evolution of an Entity" and shall exhibit the behaviour defined by clause +5.7.3. The Entity identifier is the value of the resource URI +variable entityId. Figure +6.19.3.1‑1 shows the retrieve temporal representation of an entity +interaction.

+
+ +
+
+Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction +
+

The query parameters that shall be supported are those defined in Table 6.19.3.1‑1 +and Table +6.19.3.1‑2 describes the request body and possible responses.

+
+Table 6.19.3.1-1: Query parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+attrs +
+Comma separated list of strings +
+0..1 +
+A synonym for a combination of the pick andq parameters. +Deprecated +
+
+ +
+
+Each String is an Attribute (Property or Relationship) name.
+List of Attributes to be retrieved. If not specified, all Attributes +related to the temporal representation of an Entity shall be retrieved. +
+pick +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or an Attribute name). +
+
+When defined, every Entity within the payload body is reduced down to +only contain the listed Entity members. +
+omit +
+Comma separated list of strings +
+0..1 +
+Each String is an Entity member ("id", "type", "scope” or an Attribute name). +
+
+When defined, the listed Entity members are removed from each Entity +within the payload. +
+timeproperty +
+String +
+0..1 +
+It represents a Temporal Property name.
+Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is +"observedAt". (See clause +4.8). +
+timerel +
+String +
+0..1 +
+
+It shall be 1 if timeAt is present +
+It represents the Temporal Relationship as defined by clause +4.11.
+Allowed values: "before", "after", "between". +
+timeAt +
+String +
+0..1 +
+
+It shall be 1 if timerel is present +
+It represents the timeAt parameter as defined by clause +4.11.
+It shall be a DateTime. +
+endTimeAt +
+String +
+0..1 +
+
+It shall be 1 if timerel is equal to "between" +
+It represents the endTimeAt parameter as defined by clause +4.11.
+It shall be a DateTime. +
+lastN +
+Positive integer +
+0..1 +
+Only the last n Attribute instances (under the concerned time interval) +shall be retrieved. +
+lang +
+String +
+0..1 +
+It represents the preferred natural language of the response.
+It is used to reduce languageMaps to a string or string array +property in a single preferred language. +
+aggrMethods +
+Comma separated list of strings +
+0..1 +
+
+It shall be 1 if aggregatedValues is present in the +options parameter +
+Each String represents the aggregation methods as defined by clause +4.5.19.
+Only applicable if "aggregatedValues" is present in the options parameter. +
+aggrPeriodDuration +
+String +
+0..1 +
+It represents the duration of each period used for the aggregation as +defined by clause +4.5.19.
+If not specified, it defaults to a duration of 0 seconds and is +interpreted as a duration spanning the whole time-range specified by the +temporal query. +
+
+Only applicable if "aggregatedValues" is present in the options +parameter. +
+datasetId +
+Comma separated list of strings +
+0..1 +
+Shall be valid URIs, "@none" +for including the default Attribute instances. Specifies the datasetIds +of the Attribute instances to be selected for each matched Attribute as +per clause +4.5.5. +
+
+Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal +
+1 +
+200 OK +
+A response body containing the JSON-LD temporal representation of the +target Entity containing the selected Attributes. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

6.19.3.2 DELETE

+

This method is associated to the operation "Delete Temporal Evolution +of an Entity" and shall exhibit the behaviour defined by clause +5.6.16. The Entity identifier is the value of the resource URI +variable entityId. Figure +6.19.3.2‑1 shows the delete entity interaction and Table 6.19.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction +
+
+Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body +and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

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

+

6.20.1 Description

+

This resource represents all the Attributes (Properties or +Relationships) of a Temporal Evolution of an +Entity.

+

6.20.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/ +
    • +
+

Resource URI variables for this resource are defined in Table +6.20.2‑1.

+
+Table 6.20.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+

6.20.3 Resource +methods

+

6.20.3.1 POST

+

This method is bound to the "Add Attributes to Temporal Evolution of +an Entity" operation and shall exhibit the behaviour defined by clause +5.6.12. The Entity identifier is the value of the resource URI +variable entityId. The data to be added shall be contained in the +HTTP request payload body. Figure +6.20.3.1‑1 shows the Add Attributes interaction and Table 6.20.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity +interaction +
+
+Table 6.20.3.1-1: Add Attributes to Temporal Evolution of
+an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal Fragment +
+1 +
+EntityTemporal Fragment containing a complete representation of the +Attribute instances to be added. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No content +
+All the Attributes were added successfully. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) not known +to the system, see clause 6.3.2. +
+

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

+

6.21.1 Description

+

This resource represents an Attribute (Property or Relationship) of a +Temporal Evolution of an +Entity.

+

6.21.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.21.2‑1.

+
+Table 6.21.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+

6.21.3 Resource +methods

+

6.21.3.1 DELETE

+

This method is associated to the operation "Delete Attribute from +Temporal Evolution of an Entity" and shall exhibit the behaviour defined +by clause +5.6.13. The Entity identifier is the value of the resource URI +variable entityId. The Attribute name is the value of the +resource URI variable attrId. Figure +6.21.3.1‑1 shows the “Delete Attribute from Temporal Evolution of an +Entity” interaction, Table 6.21.3.1‑1 +shows the delete parameters to be supported and Table 6.21.3.1‑2 +describes the request body and possible responses.

+
+ +
+
+Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution
+of an Entity interaction +
+
+Table 6.21.3.1-1: Delete parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+name +
+Data Type +
+Cardinality +
+Remarks +
+deleteAll +
+Boolean +
+0..1 +
+If true, all attribute instances are deleted. Otherwise (default) +only the Attribute instance specified by the datasetId is +deleted. In case neither the deleteAll flag nor a datasetId is +present, the default Attribute instance is deleted. +
+datasetId +
+String +
+0..1 +
+Shall be a valid URI. Specifies the datasetId of the dataset to +be deleted. +
+
+Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of
+an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI) or +Attribute name not known to the system. See clause 6.3.2. +
+

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

+

6.22.1 Description

+

This resource represents an Attribute (Property or Relationship) +instance of a Temporal Evolution of an +Entity.

+

6.22.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entities/{entityId}/attrs/{attrId}/{instanceId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.22.2‑1.

+
+Table 6.22.2-1: URI variables +
+ ++++ + + + + + + + + + + + + + + + + + + + + +
+Name +
+Definition +
+entityId +
+Id (URI) of the concerned entity +
+attrId +
+Attribute name (Property or Relationship) +
+instanceId +
+Id (URI) identifying a particular Attribute instance +
+

6.22.3 Resource +methods

+

6.22.3.1 PATCH

+

This method is associated to the operation "Modify attribute instance +from Temporal Evolution of an Entity" and shall exhibit the behaviour +defined by clause +5.6.14. The Entity identifier is the value of the resource URI +variable entityId. The attribute name is the value of the +resource URI variable attrId. The instance identifier is the +value of the resource URI variable instanceId. Figure +6.22.3.1‑1 shows the Modify Attribute instance interaction and Table 6.22.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution +interaction +
+
+Table 6.22.3.1-1: Modify Attribute instance from
+Temporal Evolution request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityTemporal Fragment +
+1 +
+EntityTemporal Fragment containing a complete representation of the +Attribute instance to be replaced. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI), attribute +name or instance identifier not known to the system. See clause 6.3.2. +
+

6.22.3.2 DELETE

+

This method is associated to the operation "Delete Attribute instance +from Temporal Evolution of an Entity" and shall exhibit the behaviour +defined by clause +5.6.15. The Entity identifier is the value of the resource URI +variable entityId. The Attribute name is the value of the +resource URI variable attrId. The instance identifier is the +value of the resource URI variable instanceId. Figure +6.22.3.2‑1 shows the Delete Attribute instance interaction and Table 6.22.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of +an Entity interaction +
+
+Table 6.22.3.2-1: Delete Attribute instance from
+Temporal Evolution of an Entity request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an Entity identifier (URI), attribute +name or instance identifier not known to the system. See clause 6.3.2. +
+

6.23 Resource: +entityOperations/query

+

6.23.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable querying for entities by means of a POST method. The +behaviour of this clause mirrors the one in clause 6.4.3.2, which +performs the "Query Entity" operation (defined by clause +5.7.2) by means of a GET method. The reason to provide an +alternative via POST is that, using GET:

+
    +
  1. +The client may end up assembling very long URLs, due to the URI +parameters for id, q‚ type, attrs, etc., +being included in the URL. Problems with too long URLs may arise with +some applications that cut URLs to a maximum length. +
    2. +
  2. +There is a need to URL-encode the resulting URL. By using POST, there is +no need to url-encode. +
    3. +
+

6.23.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/query +
    • +
+

6.23.3 Resource +methods

+

6.23.3.1 POST

+

This method is associated to the operation "Query Entities" and shall +exhibit the behaviour defined by clause +5.7.2. Figure +6.23.3.1‑1 shows the operation interaction and Table 6.23.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.23.3.1-1: Query Entity via POST Interaction +
+
+Table 6.23.3.1-1: Query Entity via POST Interaction and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Entity[] +
+1 +
+200 OK +
+A response body containing the query result as a list of Entities. +
+GeoJSON FeatureCollection +
+1 +
+200 OK +
+If the Accept Header indicates that the Entities are to be rendered as +GeoJSON, a response body containing the query result as GeoJSON +FeatureCollection is returned. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.24 Resource: +temporal/entityOperations/query

+

6.24.1 Description

+

A sub-resource, pertaining to the temporal/entityOperations/ +resource, intended to enable temporal querying for entities by means of +a POST method. The behaviour of this clause mirrors the one in clause 6.18.3.2, which +performs the "Query Temporal Evolution of +Entities" (defined by clause +5.7.4) operation by means of a GET method. The reason to provide an +alternative via POST is that, using GET:

+
    +
  1. +The client may end up assembling very long URLs, due to the URI +parameters for id, q‚ type, attrs, etc., +being included in the URL. Problems with too long URLs may arise with +some applications that cut URLs to a maximum length. +
    2. +
  2. +There is a need to URL-encode the resulting URL. By using POST, there is +no need to url-encode. +
    3. +
+

6.24.2 Resource +definition

+

Resource URI:

+
    +
  • +/temporal/entityOperations/query +
    • +
+

6.24.3 Resource +methods

+

6.24.3.1 POST

+

This method is associated to the operation "Query Temporal Evolution +of Entities" and shall exhibit the behaviour defined by clause +5.7.4. Figure +6.24.3.1‑1 shows the operation interaction and Table 6.24.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.24.3.1-1: Temporal Query Entity via POST Interaction +
+
+Table 6.24.3.1-1: Temporal Query Entity via POST Interaction and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Query +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the query to be performed. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTemporal[] +
+1 +
+200 OK +
+A response body containing the query result as a list of Entities. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.25 Resource: types/

+

6.25.1 Description

+

This resource represents the entity types available in an NGSI-LD +system.

+

6.25.2 Resource +definition

+

Resource URI:

+
    +
  • +/types/ +
    • +
+

6.25.3 Resource +methods

+

6.25.3.1 GET

+

This method is associated to the operations "Retrieve Available +Entity Types" and "Retrieve Details of Available Entity Types" (if the +details parameter is set to true) and shall exhibit the +behaviour defined by clauses 5.7.5 +and 5.7.6 +respectively.

+
+ +
+
+Figure 6.25.3.1-1: Retrieve Available Entity Types interaction +
+

The request parameters that shall be supported are those defined in +Table +6.25.3.1‑1 and Table 6.25.3.1‑2 +describes the request body and possible responses.

+
+Table 6.25.3.1-1: Retrieve Available Entity Types: optional parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+If true, then detailed entity type information represented as an +array with elements of the Entity Type data structure (clause +5.2.25) is to be returned +
+
+Table 6.25.3.1-2: Retrieve Available Entity Types request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTypeList +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the +EntityTypeList (clause +5.2.24) is to be returned, unless details=true is specified +
+EntityType[] +
+1 +
+200 OK +
+If details=true is specified, a response body containing a +JSON-LD array with elements of the EntityType data structure (clause +5.2.25) is to be returned +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error +
+

6.26 Resource: +types/{type}

+

6.26.1 Description

+

This resource represents the specified entity type for which entity +instances are available in an NGSI-LD system.

+

6.26.2 Resource +definition

+

Resource URI:

+
    +
  • +/types/{type} +
    • +
+

Resource URI variables for this resource are defined in Table +6.26.2‑1.

+
+Table 6.26.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+type +
+Name of the entity type for which detailed information is to be +retrieved. The Fully Qualified Name (FQN) as well as the short name can +be used, given that the latter is part of the JSON-LD @context +provided. +
+

6.26.3 Resource +methods

+

6.26.3.1 GET

+

This method is associated to the operation "Retrieve Available Entity +Type Information" and shall exhibit the behaviour defined by clause +5.7.7. The entity type is the value of the resource URI variable +"type". Figure +6.26.3.1‑1 shows the retrieve available entity type interaction.

+
+ +
+
+Figure 6.26.3.1-1: Retrieve Available Entity Type interaction +
+

Table +6.26.3.1‑1 describes the request body and possible responses.

+
+Table 6.26.3.1-1: Retrieve Available Entity Type request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityTypeInfo +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the detailed +information about the available entity type. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an entity type not known to the +system, see clause 6.3.2. +
+

6.27 Resource: +attributes/

+

6.27.1 Description

+

This resource represents the attributes available in an NGSI-LD +system.

+

6.27.2 Resource +definition

+

Resource URI:

+
    +
  • +/attributes/ +
    • +
+

6.27.3 Resource +methods

+

6.27.3.1 GET

+

This method is associated to the operations "Retrieve Available +Attributes" and "Retrieve Details of Available Attributes" (if the +details parameter is set to true) and shall exhibit the +behaviour defined by clauses 5.7.8 +and 5.7.9 +respectively.

+
+ +
+
+Figure 6.27.3.1-1: Retrieve Available Attributes interaction +
+

The request parameters that shall be supported are those defined in +Table +6.27.3.1‑1 and Table 6.27.3.1‑2 +describes the request body and possible responses.

+
+Table 6.27.3.1-1: Retrieve Available Attributes: optional parameter +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+If true, then detailed attribute information represented as an +array with elements of the Attribute data structure (clause +5.2.28) is to be returned +
+
+Table 6.27.3.1-2: Retrieve Available Attributes request body and +possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+AttributeList +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the +AttributeList (clause +5.2.27) is to be returned, unless details=true is specified. +
+Attribute[] +
+1 +
+200 OK +
+If details=true is specified, a response body containing a +JSON-LD array with elements of the Attribute data structure (clause +5.2.28) is to be returned. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.28 Resource: +attributes/{attrId}

+

6.28.1 Description

+

This resource represents the specified attribute that belongs to +entity instances existing within the NGSI-LD system.

+

6.28.2 Resource +definition

+

Resource URI:

+
    +
  • +/attributes/{attrId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.28.2‑1.

+
+Table 6.28.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+attrId +
+Name of the attribute for which detailed information is to be retrieved. +The Fully Qualified Name (FQN) as well as the short name can be used, +given that the latter is part of the JSON-LD @context provided. +
+

6.28.3 Resource +methods

+

6.28.3.1 GET

+

This method is associated to the operation "Retrieve Available +Attribute Information" and shall exhibit the behaviour defined by clause +5.7.10. The attribute is the value of the resource URI variable +"attrId". Figure +6.28.3.1‑1 shows the retrieve available attribute information +interaction.

+
+ +
+
+Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction +
+

Table +6.28.3.1‑1 describes the request body and possible responses.

+
+Table 6.28.3.1-1: Retrieve Available Attribute Information request body +and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+Attribute +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the detailed +information about the available attribute. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an attribute name not known to the +system, see clause 6.3.2. +
+

6.29 Resource: +jsonldContexts/

+

6.29.1 Description

+

This resource represents the @contexts known to an NGSI-LD +system.

+

6.29.2 Resource +definition

+

Resource URI:

+
    +
  • +/jsonldContexts/ +
    • +
+

6.29.3 Resource +methods

+

6.29.3.1 POST

+

This method is bound to the operation "Add @context" and shall +exhibit the behaviour defined by clause +5.13.2, taking the @context to be added from the HTTP request +payload body. Figure +6.29.3.1‑1 shows the Add @context interaction and Table 6.29.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.29.3.1-1: Add @context interaction +
+
+Table 6.29.3.1-1: Add @context request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+JSON Object +
+1 +
+Payload body in the request contains a JSON object that has a root node +named @context, which represents a JSON-LD "local context". +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+201 Created +
+The HTTP response shall include a "Location" HTTP header that contains the local +URI of the added @context. +
+ProblemDetails
+(see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.29.3.2 GET

+

This method is associated to the operation "List @contexts" +and shall exhibit the behaviour defined by clause +5.13.3, and it provides information about stored @contexts as +part of the HTTP response payload body. Figure +6.29.3.2‑1 shows the List @contexts interaction.

+
+ +
+
+Figure 6.29.3.2-1: List @contexts interaction +
+

The request parameters that shall be supported by implementations are +those defined in Table 6.29.3.2‑1 +and Table +6.29.3.2‑2 describes the request body and possible responses.

+
+Table 6.29.3.2-1: List @contexts request parameters +
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+Whether a list of URLs or a more detailed list of JSON Objects is +requested +
+kind +
+String +
+0..1 +
+Can be either "Cached", "Hosted", or "ImplicitlyCreated" +
+
+Table 6.29.3.2-2: List @contexts request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+String[] +
+
+or +
+
+JSON Object[] +
+1 +
+200 OK +
+A response body containing a list of URLs or a list of JSON Objects, as +defined in clause +5.13.3.5, representing metadata about stored @contexts. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.30 Resource: +jsonldContexts/{contextId}

+

6.30.1 Description

+

This resource represents a JSON-LD @context stored in the +broker's internal @context storage.

+

6.30.2 Resource +definition

+

Resource URI:

+
    +
  • +/jsonldContexts/{contextId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.30.2‑1.

+
+Table 6.30.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+contextId +
+Local identifier of the @context to be managed (served or +deleted). For @contexts of kind "Cached" this can also be the original URL the +broker downloaded the @context from. +
+

6.30.3 Resource +methods

+

6.30.3.1 GET

+

This method is associated to the operation "Serve @context" +and shall exhibit the behaviour defined by clause +5.13.4. The @context identifier is the value of the resource +URI variable "contextId". Figure +6.30.3.1‑1 shows the HTTP Serve @context interaction.

+
+ +
+
+Figure 6.30.3.1-1: Serve @context interaction +
+

The request parameters that shall be supported by implementations are +those defined in Table 6.30.3.1‑1 +and Table +6.30.3.1‑2 describes the request body and possible responses.

+
+Table 6.30.3.1-1: Serve @contexts request parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+details +
+Boolean +
+0..1 +
+Whether the content of the @context or its metadata is requested +
+
+Table 6.30.3.1-2: Serve @context request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+JSON Object +
+1 +
+200 OK +
+If the parameter details is false or missing, response body +contains a JSON object that has a root node named @context, which +represents a JSON-LD "local context". +
+
+If the parameter details is true, response body contains a JSON +object as defined in clause +5.13.4.5, which metadata of a JSON-LD "local context". +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+422 Unprocessable +
+It is used when a client indicated an @context of type "Cached", see clause 6.3.2. +
+

6.30.3.2 DELETE

+

This method is associated to the operation "Delete and Reload +@context" and shall exhibit the behaviour defined by clause +5.13.5. The Entity identifier is the value of the resource URI +variable "contextId". Figure +6.30.3.2‑1 shows the delete entity interaction. The request +parameters that shall be supported are those defined in Table 6.30.3.2‑1 +and Table +6.30.3.2‑2 describes the request body and possible responses.

+
+Table 6.30.3.2-1: Delete and Reload @context request parameters +
+ ++++++ + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Cardinality +
+Remarks +
+reload +
+Boolean +
+0..1 +
+indicates to perform a download and replace of the @context, as +specified in clause +5.13.5.4. +
+
+ +
+
+Figure 6.30.3.2-1: Delete and Reload @context interaction +
+
+Table 6.30.3.2-2: Delete and Reload @context request body and possible +responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+504 Gateway Timeout +
+It is used when re-downloading fails. +
+

6.31 Resource: +entityOperations/merge

+

6.31.1 Description

+

A sub-resource, pertaining to the entityOperations/ resource, +intended to enable batch entity merge for the NGSI-LD API.

+

6.31.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityOperations/merge +
    • +
+

6.31.3 Resource +methods

+

6.31.3.1 POST

+

This method is associated to the operation "Batch Entity Merge" and +shall exhibit the behaviour defined by clause +5.6.20. Figure +6.31.3.1‑1 shows the operation interaction and Table 6.31.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.31.3.1-1: Batch Entity Merge Interaction +
+
+Table 6.31.3.1-1: Batch Entity Merge Interaction and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+Entity[] +
+1 +
+Array of Entities to be merged. +
+Response Body +
+Data Type +
+Cardinality +
+Response Code +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+If all entities have been successfully merged, there is no payload body +in the response. +
+BatchOperationResult +
+1 +
+207 Multi-Status +
+If only some or none of the entities have been successfully merged, a +response body containing the result of each operation contained in the +batch is returned in a BatchOperationResult structure. It +contains two arrays. The first array (success) contains the URIs +of the successfully merged entities, while the second array +(errors) contains information about the error for each of the +entities that could not be merged-patched. There is no restriction as to +the order of the Entity IDs in the arrays. +
+
+ +
+
+If any of the entities matches to a registration, the relevant parts of +the request are forwarded as a distributed operation. +
+
+ +
+
+In the case when an error response is received back from any distributed +operation, a response body containing the result returned from each +registration is returned in a BatchOperationResult structure. +
+
+ +
+
+Errors can occur whenever a distributed operation is unsupported, fails +or times out, see clause +6.3.17. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+

6.32 Resource: +entityMaps/{entityMapId}

+

6.32.1 Description

+

This resource represents an EntityMap available in the broker's +internal storage or memory.

+

6.32.2 Resource +definition

+

Resource URI:

+
    +
  • +/entityMaps/{entityMapId} +
    • +
+

Resource URI variables for this resource are defined in Table +6.32.2‑1.

+
+Table 6.32.2-1: URI variables +
+ ++++ + + + + + + + + + + + + +
+Name +
+Definition +
+entityMapId +
+Id (URI) of the EntityMap to be retrieved, updated or deleted. +
+

6.32.3 Resource +methods

+

6.32.3.1 GET

+

This method is associated to the operation "Retrieve EntityMap" and +shall exhibit the behaviour defined by clause +5.14.1. The EntityMap identifier is the value of the resource URI +variable "entityMapId". Figure +6.32.3.1‑1 shows the Retrieve EntityMap interaction and Table 6.32.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.3.1-1: Retrieve EntityMap +
+
+Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+EntityMap +
+1 +
+200 OK +
+A response body containing the JSON-LD representation of the target +entity +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an EntityMap identifier not known to +the system, see clause 6.3.2. +
+

6.32.3.2 PATCH

+

This method is associated to the operation "Update EntityMap" and +shall exhibit the behaviour defined by clause +5.14.2. The EntityMap identifier is the value of the resource URI +variable "entityMapId". Figure +6.32.3.2‑1 shows the Update EntityMap interaction and Table 6.32.3.2‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.2.2-1: Update EntityMap +
+
+Table 6.32.3.2-1: Update EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+EntityMap +
+1 +
+Payload body in the request contains a JSON-LD object which represents +the context source registration that is to be updated. +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an EntityMap identifier not known to +the system, see clause 6.3.2. +
+
+ +
+

6.32.3.3 DELETE

+

This method is associated to the operation "Delete EntityMap" and +shall exhibit the behaviour defined by clause +5.14.3. The Entity identifier is the value of the resource URI +variable "contextId". Figure +6.32.3.3‑1 shows the delete entity interaction and Table 6.32.3.3‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.32.3.3-1: Delete and Reload @context interaction +
+
+Table 6.32.3.3-1: Delete EntityMap request body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+N/A +
+N/A +
+204 No Content +
+ +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+400 Bad Request +
+It is used to indicate that the request or its content is incorrect, see +clause 6.3.2. +
+
+In the returned ProblemDetails structure, the detail +attribute should convey more information about the error. +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+404 Not Found +
+It is used when a client provided an @context identifier not +known to the system, see clause 6.3.2. +
+

6.33 Resource: +info/sourceIdentity

+

6.33.1 Description

+

This resource represents identity information about the Context Source itself.

+

6.33.2 Resource +definition

+

Resource URI:

+
    +
  • +/info/sourceIdentity +
    • +
+

6.33.3 Resource +methods

+

6.33.3.1 GET

+

This method is associated to the operation "Retrieve Context Source +Identity Information" and shall exhibit the behaviour defined by clause +5.15.1. Figure 6.33.3.1‑1 shows the +Retrieve Context Source Identity Information interaction and table 6.33.3.1‑1 +describes the request body and possible responses.

+
+ +
+
+Figure 6.33.1.1-1: Retrieve Context Source Identity Information +
+
+Table 6.33.3.1-1: Retrieve Context Source Identity Information request +body and possible responses +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Request Body +
+Data Type +
+Cardinality +
+Remarks +
+N/A +
+N/A +
+ +
+Response Body +
+Data Type +
+Cardinality +
+Response Codes +
+Remarks +
+ContextSourceIdentity +
+1 +
+200 No Content +
+A response body containing the JSON-LD representation of the Context +Source Identity Information +
+ProblemDetails (see IETF RFC 7807 [10]) +
+1 +
+501 Not Implemented +
+It is used by Context Sources to +indicate that retrieval of the Context Source information is unsupported +see . +
+
+ + diff --git a/public/12-tabapi-mqtt-notification-binding.html b/public/12-tabapi-mqtt-notification-binding.html new file mode 100644 index 0000000000000000000000000000000000000000..2585cd739ca09398ca33ba536b344f89434d182b --- /dev/null +++ b/public/12-tabapi-mqtt-notification-binding.html @@ -0,0 +1,3015 @@ + + + + + + + 7 API MQTT Notification Binding + + + + + + + + +

7 API MQTT Notification +Binding

+

7.1 Introduction

+

This clause defines the optional support of the NGSI-LD API for +sending notifications via the MQTT protocol [24] and [25]. The subscriptions are +handled using the HTTP binding as described in clause 6, but +instead of an HTTP endpoint, an MQTT endpoint is provided.

+

7.2 Notification +behaviour

+

In case a subscription received via HTTP specifies an MQTT endpoint +in the "notification.endpoint.uri" member of the subscription structure +(defined by clauses 5.2.12, +5.2.14 +and 5.2.15), and +the MQTT notification binding is supported by the NGSI-LD +implementation, notifications related to this subscription shall be sent +via the MQTT protocol.

+

The syntax of an MQTT endpoint URI is mqtt[s]://[<username>][:<password>]@<host>[:<port>]/<topic>[/<subtopic>]* +and follows an existing convention for representing an MQTT endpoint as +a URI [i.19].

+

Username and password can be optionally specified as part of the +endpoint URI. If the port is not explicitly specified, the default MQTT +port is 1883 for MQTT over TCP and 8883 for mqtts, i.e. Secure MQTT over +TLS. MQTT supports the structuring of topics as a hierarchy with any +number of subtopic levels, which can be specified as part of the +endpoint URI.

+

In MQTT, all non-protocol information has to be included into the +MQTT message. This means that the actual notification as specified in clause +5.3.1, as well as additional information like MIME type, possibly +the link to the @context and additional user-specified +information, which in the HTTP case is provided as headers, has to be +included into the MQTT message. The MQTT notification message shall be +provided as a JSON Object with the two elements "metadata" and "body". The actual notification, as specified +in clause +5.3.1 is the value of "body", whereas +any additional information is provided as key-value pairs in "metadata".

+

For the MQTT protocol, there are currently two versions supported, +MQTTv3.1.1 [24] and +MQTTv5.0 [25]. Also, +there are three levels of quality of service:

+
    +
  • +at most once (0); +
    • +
  • +at least once (1); and +
    • +
  • +exactly once (2). +
    • +
+

These can be specified in the subscription as part of the optional +array of KeyValuePair type (defined by clause +5.2.22) "notification.endpoint.notifierInfo". The MQTT protocol +parameters can be found in Table +7.2‑1. If not present, the given default value is used.

+
+Table 7.2-1: Protocol parameters for MQTT in notifierInfo +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Key +
+Possible Values +
+Default +
+Source +
+Description +
+MQTT-Version +
+mqtt3.1.1, mqtt5.0 +
+mqtt5.0 +
+Subscription's notification.endpoint +
+
+.notifierInfo +
+Version of MQTT protocol +
+MQTT-QoS +
+0, 1, 2 +
+0 +
+Subscription's notification.endpoint +
+
+.notifierInfo +
+MQTT Quality of service, at most once (0), at least once (1) and exactly +once (2) +
+

The MIME type associated with the notification shall be "application/json" by default. However, this +can be changed to "application/ld+json" by means of the "endpoint.accept" member. The +MIME type is specified as Content-Type in the "metadata" element of the MQTT message. If the +target MIME type is "application/json" +then the reference to the JSON-LD @context is provided as Link in +the "metadata" element of the MQTT +message, following the specification of the HTTP Link header as mandated +by the JSON-LD specification [2], section 6.2 (to the +default JSON-LD @context if none available). Table +7.2‑2 lists these "receiver side" metadata parameters.

+
+Table 7.2-2: Parameters for MQTT in "metadata" +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Key +
+Possible Values +
+Default +
+Source +
+Description +
+Content-Type +
+"application/json", "application/ld+json" +
+"application/json" +
+Subscription's +
+
+notification +
+
+.endpoint.accept +
+MIME type of the notification included in the "body" element of the MQTT message +
+Link +
+Same format as specified in JSON-LD specification [2], section 6.2 for the HTTP +Link header +
+ +
+Link Header provided in Subscription +
+Contains the reference to the @context in case Content-Type is +"application/json". Example:
+<http://myhost.org/mycontext>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

Additionally, if the optional array of KeyValuePair type (defined by +clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new entry for each member named "key" of +the key, value pairs that make up the array shall be generated and added +to the "metadata" element of the MQTT +message. The content of each entry shall be set equal to the content of +the corresponding "value" member of the KeyValuePair.

+ + diff --git a/public/13-annex-a-normative-ngsi-ld-identifier-considerations.html b/public/13-annex-a-normative-ngsi-ld-identifier-considerations.html new file mode 100644 index 0000000000000000000000000000000000000000..f2aeb9bc0dfe1a962811ba802471d244564528d9 --- /dev/null +++ b/public/13-annex-a-normative-ngsi-ld-identifier-considerations.html @@ -0,0 +1,2830 @@ + + + + + + + Annex A (normative): NGSI-LD identifier +considerations + + + + + + + + +

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

+

A.1 Introduction

+

The purpose of identifiers is to allow uniquely identifying NGSI-LD +elements (Entities, Context Subscriptions or Context Source Registrations) within an +NGSI-LD system. This annex is intended to clarify the different issues +around the design of identifiers in NGSI-LD.

+

A.2 Entity +identifiers

+

In order to enable the participation of NGSI-LD in linked data +scenarios, all Entities are identified by URIs. If +those URIs are expected to participate in external linked data +relationships they should be dereferenceable.

+

It is noteworthy that the identifier from the point of view of +NGSI-LD is different from the inherent identifier that a specific Entity +may have. For instance, an NGSI-LD Entity of Type "Vehicle" may have a Property named +licencePlateNumber, which it is actually a unique identifier from +the point of view of the Entity domain, as it uniquely identifies the +specific vehicle instance. However, from the point of view of the +NGSI-LD system, it may have another identifier which might or might not +include such licence plate number identifier.

+

A.3 NGSI-LD +namespace

+

NGSI-LD defines a specific URN [9] namespace intended to help +API users to design readable, clean and simple identifiers. As it is +based on URNs, the usage of this identification approach is not +recommended when dereferenceable URIs are needed (fully-fledged linked +data scenarios).

+

The referred namespace is defined as follows (to be registered with +IANA):

+
    +
  • +namespace identifier: NID = "ngsi-ld" +
    • +
  • +namespace specific string: NSS = EntityTypeName ":" EntityIdentificationString +
    • +
+

EntityTypeName shall be an Entity Type name which can be +expanded to a URI as per the @context.

+

EntityIdentificationString shall be a string that allows +uniquely identifying the subject Entity in combination with the other +items being part of the NSS.

+
+
+EXAMPLE: +
+
+ +urn:ngsi-ld:Person:28976543 +. +
+
+

It is recommended that applications use this URN namespace when +applicable.

+

In general, the URN specification defines namespace equivalence in a +case-insensitive manner, however it is assumed that context-broker +implementations shall always use lowercase letters in namespaces where +they have a choice in case, unless there is a strong reason otherwise. +Restricting the namespace prefix to lower case urn:ngsi-ld: can improve caching and retrieval, +since this ensures since alphabetic characters within the namespace +specific string are always consistent.

+ + diff --git a/public/13-tabapi-mqtt-notification-binding.html b/public/13-tabapi-mqtt-notification-binding.html new file mode 100644 index 0000000000000000000000000000000000000000..a90ed2074dd47f4cd815432c229db7ad6500c91e --- /dev/null +++ b/public/13-tabapi-mqtt-notification-binding.html @@ -0,0 +1,2888 @@ + + + + + + + 7 API MQTT Notification Binding + + + + + + + +
+

7 API MQTT +Notification Binding

+

7.1 Introduction

+

This clause defines the optional support of the NGSI-LD API for +sending notifications via the MQTT protocol [24] and [25]. The subscriptions are +handled using the HTTP binding as described in clause 6, but +instead of an HTTP endpoint, an MQTT endpoint is provided.

+

7.2 Notification +behaviour

+

In case a subscription received via HTTP specifies an MQTT endpoint +in the "notification.endpoint.uri" member of the subscription structure +(defined by clauses 5.2.12, +5.2.14 +and 5.2.15), and +the MQTT notification binding is supported by the NGSI-LD +implementation, notifications related to this subscription shall be sent +via the MQTT protocol.

+

The syntax of an MQTT endpoint URI is mqtt[s]://[<username>][:<password>]@<host>[:<port>]/<topic>[/<subtopic>]* +and follows an existing convention for representing an MQTT endpoint as +a URI [i.19].

+

Username and password can be optionally specified as part of the +endpoint URI. If the port is not explicitly specified, the default MQTT +port is 1883 for MQTT over TCP and 8883 for mqtts, i.e. Secure MQTT over +TLS. MQTT supports the structuring of topics as a hierarchy with any +number of subtopic levels, which can be specified as part of the +endpoint URI.

+

In MQTT, all non-protocol information has to be included into the +MQTT message. This means that the actual notification as specified in clause +5.3.1, as well as additional information like MIME type, possibly +the link to the @context and additional user-specified +information, which in the HTTP case is provided as headers, has to be +included into the MQTT message. The MQTT notification message shall be +provided as a JSON Object with the two elements "metadata" and "body". The actual notification, as specified +in clause +5.3.1 is the value of "body", whereas +any additional information is provided as key-value pairs in "metadata".

+

For the MQTT protocol, there are currently two versions supported, +MQTTv3.1.1 [24] and +MQTTv5.0 [25]. Also, +there are three levels of quality of service:

+
    +
  • +at most once (0); +
    • +
  • +at least once (1); and +
    • +
  • +exactly once (2). +
    • +
+

These can be specified in the subscription as part of the optional +array of KeyValuePair type (defined by clause +5.2.22) "notification.endpoint.notifierInfo". The MQTT protocol +parameters can be found in Table +7.2‑1. If not present, the given default value is used.

+
+Table 7.2-1: Protocol parameters for MQTT in notifierInfo +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Key +
+Possible Values +
+Default +
+Source +
+Description +
+MQTT-Version +
+mqtt3.1.1, mqtt5.0 +
+mqtt5.0 +
+Subscription's notification.endpoint +
+
+.notifierInfo +
+Version of MQTT protocol +
+MQTT-QoS +
+0, 1, 2 +
+0 +
+Subscription's notification.endpoint +
+
+.notifierInfo +
+MQTT Quality of service, at most once (0), at least once (1) and exactly +once (2) +
+

The MIME type associated with the notification shall be "application/json" by default. However, this +can be changed to "application/ld+json" by means of the "endpoint.accept" member. The +MIME type is specified as Content-Type in the "metadata" element of the MQTT message. If the +target MIME type is "application/json" +then the reference to the JSON-LD @context is provided as Link in +the "metadata" element of the MQTT +message, following the specification of the HTTP Link header as mandated +by the JSON-LD specification [2], section 6.2 (to the +default JSON-LD @context if none available). Table +7.2‑2 lists these "receiver side" metadata parameters.

+
+Table 7.2-2: Parameters for MQTT in "metadata" +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Key +
+Possible Values +
+Default +
+Source +
+Description +
+Content-Type +
+"application/json", "application/ld+json" +
+"application/json" +
+Subscription's +
+
+notification +
+
+.endpoint.accept +
+MIME type of the notification included in the "body" element of the MQTT message +
+Link +
+Same format as specified in JSON-LD specification [2], section 6.2 for the HTTP +Link header +
+ +
+Link Header provided in Subscription +
+Contains the reference to the @context in case Content-Type is +"application/json". Example:
+<http://myhost.org/mycontext>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

Additionally, if the optional array of KeyValuePair type (defined by +clause +5.2.22) notification.endpoint.receiverInfo of the +subscription is present, then a new entry for each member named "key" of +the key, value pairs that make up the array shall be generated and added +to the "metadata" element of the MQTT +message. The content of each entry shall be set equal to the content of +the corresponding "value" member of the KeyValuePair.

+
+ + diff --git a/public/14-annex-a-normative-ngsi-ld-identifier-considerations.html b/public/14-annex-a-normative-ngsi-ld-identifier-considerations.html new file mode 100644 index 0000000000000000000000000000000000000000..e094be1b2bb22af28bd6ddb4c6206812cbf9bf9f --- /dev/null +++ b/public/14-annex-a-normative-ngsi-ld-identifier-considerations.html @@ -0,0 +1,2696 @@ + + + + + + + Annex A (normative): NGSI-LD identifier considerations + + + + + + + +
+

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

+

A.1 Introduction

+

The purpose of identifiers is to allow uniquely identifying NGSI-LD +elements (Entities, Context Subscriptions or Context Source Registrations) within an +NGSI-LD system. This annex is intended to clarify the different issues +around the design of identifiers in NGSI-LD.

+

A.2 Entity +identifiers

+

In order to enable the participation of NGSI-LD in linked data +scenarios, all Entities are identified by URIs. If +those URIs are expected to participate in external linked data +relationships they should be dereferenceable.

+

It is noteworthy that the identifier from the point of view of +NGSI-LD is different from the inherent identifier that a specific Entity +may have. For instance, an NGSI-LD Entity of Type "Vehicle" may have a Property named +licencePlateNumber, which it is actually a unique identifier from +the point of view of the Entity domain, as it uniquely identifies the +specific vehicle instance. However, from the point of view of the +NGSI-LD system, it may have another identifier which might or might not +include such licence plate number identifier.

+

A.3 NGSI-LD +namespace

+

NGSI-LD defines a specific URN [9] namespace intended to help +API users to design readable, clean and simple identifiers. As it is +based on URNs, the usage of this identification approach is not +recommended when dereferenceable URIs are needed (fully-fledged linked +data scenarios).

+

The referred namespace is defined as follows (to be registered with +IANA):

+
    +
  • +namespace identifier: NID = "ngsi-ld" +
    • +
  • +namespace specific string: NSS = EntityTypeName ":" EntityIdentificationString +
    • +
+

EntityTypeName shall be an Entity Type name which can be +expanded to a URI as per the @context.

+

EntityIdentificationString shall be a string that allows +uniquely identifying the subject Entity in combination with the other +items being part of the NSS.

+
+EXAMPLE: urn:ngsi-ld:Person:28976543. +
+

It is recommended that applications use this URN namespace when +applicable.

+

In general, the URN specification defines namespace equivalence in a +case-insensitive manner, however it is assumed that context-broker +implementations shall always use lowercase letters in namespaces where +they have a choice in case, unless there is a strong reason otherwise. +Restricting the namespace prefix to lower case urn:ngsi-ld: can improve caching and retrieval, +since this ensures since alphabetic characters within the namespace +specific string are always consistent.

+
+ + diff --git a/public/14-annex-b-normative-core-ngsi-ld-context-definition.html b/public/14-annex-b-normative-core-ngsi-ld-context-definition.html new file mode 100644 index 0000000000000000000000000000000000000000..f28b5644f8aea2e959e6ecf00f06b9852a7ca23a --- /dev/null +++ b/public/14-annex-b-normative-core-ngsi-ld-context-definition.html @@ -0,0 +1,4107 @@ + + + + + + + Annex B (normative): Core NGSI-LD @context +definition + + + + + + + + +

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

+

Below is the definition of the Core NGSI-LD @context which +shall be supported by implementations.

+

Such definition has been tested using [i.7].

+
+{ +
+
+  "@context": { +
+
+    "@version": 1.1, +
+
+    "@protected": true, +
+
+    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", +
+
+    "geojson": "https://purl.org/geojson/vocab#", +
+
+    "id": "@id", +
+
+    "type": "@type", +
+
+    "Attribute": "ngsi-ld:Attribute", +
+
+    "AttributeList": "ngsi-ld:AttributeList", +
+
+"ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity", +
+
+    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", +
+
+    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", +
+
+    "Date": "ngsi-ld:Date", +
+
+    "DateTime": "ngsi-ld:DateTime", +
+
+    "EntityType": "ngsi-ld:EntityType", +
+
+    "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", +
+
+    "EntityTypeList": "ngsi-ld:EntityTypeList", +
+
+    "Feature": "geojson:Feature", +
+
+    "FeatureCollection": "geojson:FeatureCollection", +
+
+    "GeoProperty": "ngsi-ld:GeoProperty", +
+
+"GeometryCollection": "geojson:GeometryCollection", +
+
+"JsonProperty": "ngsi-ld:JsonProperty", +
+
+    "LanguageProperty": "ngsi-ld:LanguageProperty", +
+
+    "LineString": "geojson:LineString", +
+
+    "ListProperty": "ngsi-ld:ListProperty", +
+
+    "ListRelationship": "ngsi-ld:ListRelationship", +
+
+    "MultiLineString": "geojson:MultiLineString", +
+
+    "MultiPoint": "geojson:MultiPoint", +
+
+    "MultiPolygon": "geojson:MultiPolygon", +
+
+    "Notification": "ngsi-ld:Notification", +
+
+    "Point": "geojson:Point", +
+
+    "Polygon": "geojson:Polygon", +
+
+    "Property": "ngsi-ld:Property", +
+
+    "Relationship": "ngsi-ld:Relationship", +
+
+    "Subscription": "ngsi-ld:Subscription", +
+
+    "TemporalProperty": "ngsi-ld:TemporalProperty", +
+
+    "Time": "ngsi-ld:Time", +
+
+    "VocabProperty": "ngsi-ld:VocabProperty", +
+
+    "accept": "ngsi-ld:accept", +
+
+    "attributeCount": "attributeCount", +
+
+    "attributeDetails": "attributeDetails", +
+
+    "attributeList": { +
+
+      "@id": "ngsi-ld:attributeList", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributeName": { +
+
+      "@id": "ngsi-ld:attributeName", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributeNames": { +
+
+      "@id": "ngsi-ld:attributeNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributeTypes": { +
+
+      "@id": "ngsi-ld:attributeTypes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributes": { +
+
+      "@id": "ngsi-ld:attributes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attrs": "ngsi-ld:attrs", +
+
+    "avg": { +
+
+      "@id": "ngsi-ld:avg", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "bbox": { +
+
+      "@container": "@list", +
+
+      "@id": "geojson:bbox" +
+
+    }, +
+
+    "cacheDuration": "ngsi-ld:cacheDuration", +
+
+    "containedBy": "ngsi-ld:isContainedBy", +
+
+    "contextSourceAlias": "ngsi-ld:contextSourceAlias", +
+
+    "contextSourceExtras": { +
+
+      "@id": "ngsi-ld:contextSourceExtras", +
+
+      "@type": "@json" +
+
+    }, +
+
+    "contextSourceInfo": "ngsi-ld:contextSourceInfo", +
+
+    "contextSourceTimeAt": { +
+
+      "@id": "ngsi-ld:contextSourceTimeAt", +
+
+      "@type": "DateTime" +
+
+},  +
+
+"contextSourceUptime": "ngsi-ld:contextSourceUptime", +
+
+    "cooldown": "ngsi-ld:cooldown", +
+
+    "coordinates": { +
+
+      "@container": "@list", +
+
+      "@id": "geojson:coordinates" +
+
+    }, +
+
+    "createdAt": { +
+
+      "@id": "ngsi-ld:createdAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "csf": "ngsi-ld:csf", +
+
+    "data": "ngsi-ld:data", +
+
+"dataset": { +
+
+"@id": "ngsi-ld:hasDataset", +
+
+      "@container": "@index" +
+
+    }, +
+
+"datasetId": { +
+
+"@id": "ngsi-ld:datasetId", +
+
+"@type": "@id" +
+
+    }, +
+
+    "deletedAt": { +
+
+      "@id": "ngsi-ld:deletedAt", +
+
+      "@type": "DateTime" +
+
+    },  +
+
+    "description": "http://purl.org/dc/terms/description", +
+
+    "detail": "ngsi-ld:detail", +
+
+    "distinctCount": { +
+
+      "@id": "ngsi-ld:distinctCount", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "endAt": { +
+
+      "@id": "ngsi-ld:endAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "endTimeAt": { +
+
+      "@id": "ngsi-ld:endTimeAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "endpoint": "ngsi-ld:endpoint", +
+
+    "entities": "ngsi-ld:entities", +
+
+    "entity": "ngsi-ld:entity", +
+
+    "entityCount": "ngsi-ld:entityCount", +
+
+    "entityId": { +
+
+      "@id": "ngsi-ld:entityId", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "entityList": { +
+
+      "@id": "ngsi-ld:entityList", +
+
+      "@container": "@list" +
+
+    }, +
+
+"entityMap": "ngsi-ld:hasEntityMap", +
+
+    "error": "ngsi-ld:error", +
+
+    "errors": "ngsi-ld:errors", +
+
+    "expandValues": "ngsi-ld:expandValues", +
+
+    "expiresAt": { +
+
+      "@id": "ngsi-ld:expiresAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "features": { +
+
+      "@container": "@set", +
+
+      "@id": "geojson:features" +
+
+    }, +
+
+    "format": "ngsi-ld:format", +
+
+    "geoQ": "ngsi-ld:geoQ", +
+
+    "geometry": "geojson:geometry", +
+
+    "geoproperty": "ngsi-ld:geoproperty", +
+
+    "georel": "ngsi-ld:georel", +
+
+    "idPattern": "ngsi-ld:idPattern", +
+
+    "information": "ngsi-ld:information", +
+
+    "instanceId": { +
+
+      "@id": "ngsi-ld:instanceId", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "isActive": "ngsi-ld:isActive", +
+
+    "join": "ngsi-ld:join", +
+
+    "joinLevel": "ngsi-ld:hasJoinLevel", +
+
+    "json": { +
+
+      "@id": "ngsi-ld:hasJSON", "@type": "@json" +
+
+    }, +
+
+    "jsonKeys": "ngsi-ld:jsonKeys", +
+
+    "jsons": { +
+
+      "@id": "ngsi-ld:jsons", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "key": "ngsi-ld:hasKey", +
+
+    "lang": "ngsi-ld:lang", +
+
+    "languageMap": { +
+
+      "@id": "ngsi-ld:hasLanguageMap", +
+
+      "@container": "@language" +
+
+    }, +
+
+    "languageMaps": { +
+
+      "@id": "ngsi-ld:hasLanguageMaps", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "langString": +"http://www.w3.org/1999/02/22-rdf-syntax-ns#langString", +
+
+    "lastFailure": { +
+
+      "@id": "ngsi-ld:lastFailure", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "lastNotification": { +
+
+      "@id": "ngsi-ld:lastNotification", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "lastSuccess": { +
+
+      "@id": "ngsi-ld:lastSuccess", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "linkedMaps": "ngsi-ld:linkedMaps", +
+
+    "localOnly": "ngsi-ld:localOnly", +
+
+    "location": "ngsi-ld:location", +
+
+    "management": "ngsi-ld:management", +
+
+    "managementInterval": "ngsi-ld:managementInterval", +
+
+    "max": { +
+
+      "@id": "ngsi-ld:max", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "min": { +
+
+      "@id": "ngsi-ld:min", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "mode": "ngsi-ld:mode", +
+
+    "modifiedAt": { +
+
+      "@id": "ngsi-ld:modifiedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "notification": "ngsi-ld:notification", +
+
+    "notificationTrigger": "ngsi-ld:notificationTrigger", +
+
+    "notifiedAt": { +
+
+      "@id": "ngsi-ld:notifiedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "notifierInfo": "ngsi-ld:notifierInfo", +
+
+    "notUpdated": "ngsi-ld:notUpdated", +
+
+    "object": { +
+
+      "@id": "ngsi-ld:hasObject", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "objectList": { +
+
+      "@id": "ngsi-ld:hasObjectList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "objects": { +
+
+      "@id": "ngsi-ld:hasObjects", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "objectLists": { +
+
+      "@id": "ngsi-ld:hasObjectLists", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "objectType": { +
+
+      "@id": "ngsi-ld:hasObjectType", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "observationInterval": "ngsi-ld:observationInterval", +
+
+    "observationSpace": "ngsi-ld:observationSpace", +
+
+    "observedAt": { +
+
+      "@id": "ngsi-ld:observedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "omit": "ngsi-ld:omit", +
+
+    "operationSpace": "ngsi-ld:operationSpace", +
+
+    "pick": "ngsi-ld:pick", +
+
+    "operations": "ngsi-ld:operations", +
+
+    "previousJson": { +
+
+      "@id": "ngsi-ld:hasPreviousJson", +
+
+      "@type": "@json" +
+
+    }, +
+
+    "previousLanguageMap": { +
+
+      "@id": "ngsi-ld:hasPreviousLanguageMap", +
+
+      "@container": "@language" +
+
+    }, +
+
+    "previousObject": { +
+
+      "@id": "ngsi-ld:hasPreviousObject", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "previousObjectList": { +
+
+      "@id": "ngsi-ld:hasPreviousObjectList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "previousValue": "ngsi-ld:hasPreviousValue", +
+
+    "previousValueList": { +
+
+      "@id": "ngsi-ld:hasPreviousValueList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "previousVocab": { +
+
+      "@id": "ngsi-ld:hasPreviousVocab", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "properties": "geojson:properties", +
+
+    "propertyNames": { +
+
+      "@id": "ngsi-ld:propertyNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "q": "ngsi-ld:q", +
+
+    "reason": "ngsi-ld:reason", +
+
+    "receiverInfo": "ngsi-ld:receiverInfo", +
+
+    "refreshRate": "ngsi-ld:refreshRate", +
+
+    "registrationId": "ngsi-ld:registrationId", +
+
+    "registrationName": "ngsi-ld:registrationName", +
+
+    "relationshipNames": { +
+
+      "@id": "ngsi-ld:relationshipNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+"scope": "ngsi-ld:scope", +
+
+"scopeQ": "ngsi-ld:scopeQ", +
+
+"showChanges": "ngsi-ld:showChanges", +
+
+    "startAt": { +
+
+      "@id": "ngsi-ld:startAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "status": "ngsi-ld:status", +
+
+    "stddev": { +
+
+      "@id": "ngsi-ld:stddev", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "subscriptionId": { +
+
+      "@id": "ngsi-ld:subscriptionId", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "subscriptionName": "ngsi-ld:subscriptionName", +
+
+    "success": { +
+
+      "@id": "ngsi-ld:success", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "sum": { +
+
+      "@id": "ngsi-ld:sum", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "sumsq": { +
+
+      "@id": "ngsi-ld:sumsq", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "sysAttrs": "ngsi-ld:sysAttrs", +
+
+    "temporalQ": "ngsi-ld:temporalQ", +
+
+    "tenant": { +
+
+      "@id": "ngsi-ld:tenant", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "throttling": "ngsi-ld:throttling", +
+
+    "timeAt": { +
+
+      "@id": "ngsi-ld:timeAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "timeInterval": "ngsi-ld:timeInterval", +
+
+    "timeout": "ngsi-ld:timeout", +
+
+    "timeproperty": "ngsi-ld:timeproperty", +
+
+    "timerel": "ngsi-ld:timerel", +
+
+    "timesFailed": "ngsi-ld:timesFailed", +
+
+    "timesSent": "ngsi-ld:timesSent", +
+
+    "title": "http://purl.org/dc/terms/title", +
+
+    "totalCount": { +
+
+      "@id": "ngsi-ld:totalCount", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "triggerReason": "ngsi-ld:triggerReason", +
+
+    "typeList": { +
+
+      "@id": "ngsi-ld:typeList", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "typeName": { +
+
+      "@id": "ngsi-ld:typeName", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "typeNames": { +
+
+      "@id": "ngsi-ld:typeNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "unchanged": "ngsi-ld:unchanged", +
+
+    "unitCode": "ngsi-ld:unitCode", +
+
+    "updated": "ngsi-ld:updated", +
+
+    "uri": "ngsi-ld:uri", +
+
+    "value": "ngsi-ld:hasValue", +
+
+    "valueList": { +
+
+      "@id": "ngsi-ld:hasValueList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "valueLists": { +
+
+      "@id": "ngsi-ld:hasValueLists", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "values": { +
+
+      "@id": "ngsi-ld:hasValues", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "valueType": { +
+
+"@id": "ngsi-ld:hasValueType", +
+
+"@type": "@vocab" +
+
+}, +
+
+    "vocab": { +
+
+      "@id": "ngsi-ld:hasVocab", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "vocabs": { +
+
+      "@id": "ngsi-ld:hasVocabs", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "watchedAttributes": { +
+
+      "@id": "ngsi-ld:watchedAttributes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" +
+
+  } +
+
+} +
+
+ +
+
+
+NOTE: +
+
+Implementers + +can + +take + +advantage + +of + +prefixed + +terms, + +i.e. + +in + +the + +form + +ngsi-ld:term, + +to + +provide + +a + +terser + +representation + +of + +the + +Core + +@context +. +
+
+ + diff --git a/public/15-annex-b-normative-core-ngsi-ld-context-definition.html b/public/15-annex-b-normative-core-ngsi-ld-context-definition.html new file mode 100644 index 0000000000000000000000000000000000000000..42fe8c0b6951b29445525e2efedd3bdbbb47e5a9 --- /dev/null +++ b/public/15-annex-b-normative-core-ngsi-ld-context-definition.html @@ -0,0 +1,3917 @@ + + + + + + + Annex B (normative): Core NGSI-LD @context definition + + + + + + + +
+

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

+

Below is the definition of the Core NGSI-LD @context which +shall be supported by implementations.

+

Such definition has been tested using [i.7].

+
+{ +
+
+  "@context": { +
+
+ "@version": 1.1, +
+
+    "@protected": true, +
+
+    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", +
+
+    "geojson": "https://purl.org/geojson/vocab#", +
+
+    "id": "@id", +
+
+    "type": "@type", +
+
+ "Attribute": "ngsi-ld:Attribute", +
+
+ "AttributeList": "ngsi-ld:AttributeList", +
+
+"ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity", +
+
+    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", +
+
+    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", +
+
+    "Date": "ngsi-ld:Date", +
+
+    "DateTime": "ngsi-ld:DateTime", +
+
+ "EntityType": "ngsi-ld:EntityType", +
+
+ "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", +
+
+ "EntityTypeList": "ngsi-ld:EntityTypeList", +
+
+    "Feature": "geojson:Feature", +
+
+    "FeatureCollection": "geojson:FeatureCollection", +
+
+    "GeoProperty": "ngsi-ld:GeoProperty", +
+
+"GeometryCollection": "geojson:GeometryCollection", +
+
+"JsonProperty": "ngsi-ld:JsonProperty", +
+
+ "LanguageProperty": "ngsi-ld:LanguageProperty", +
+
+    "LineString": "geojson:LineString", +
+
+ "ListProperty": "ngsi-ld:ListProperty", +
+
+ "ListRelationship": "ngsi-ld:ListRelationship", +
+
+    "MultiLineString": "geojson:MultiLineString", +
+
+    "MultiPoint": "geojson:MultiPoint", +
+
+    "MultiPolygon": "geojson:MultiPolygon", +
+
+    "Notification": "ngsi-ld:Notification", +
+
+    "Point": "geojson:Point", +
+
+    "Polygon": "geojson:Polygon", +
+
+    "Property": "ngsi-ld:Property", +
+
+    "Relationship": "ngsi-ld:Relationship", +
+
+    "Subscription": "ngsi-ld:Subscription", +
+
+    "TemporalProperty": "ngsi-ld:TemporalProperty", +
+
+    "Time": "ngsi-ld:Time", +
+
+    "VocabProperty": "ngsi-ld:VocabProperty", +
+
+    "accept": "ngsi-ld:accept", +
+
+ "attributeCount": "attributeCount", +
+
+ "attributeDetails": "attributeDetails", +
+
+    "attributeList": { +
+
+      "@id": "ngsi-ld:attributeList", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributeName": { +
+
+   "@id": "ngsi-ld:attributeName", +
+
+      "@type": "@vocab" +
+
+ }, +
+
+    "attributeNames": { +
+
+      "@id": "ngsi-ld:attributeNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributeTypes": { +
+
+      "@id": "ngsi-ld:attributeTypes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "attributes": { +
+
+      "@id": "ngsi-ld:attributes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+ "attrs": "ngsi-ld:attrs", +
+
+    "avg": { +
+
+      "@id": "ngsi-ld:avg", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "bbox": { +
+
+      "@container": "@list", +
+
+      "@id": "geojson:bbox" +
+
+    }, +
+
+    "cacheDuration": "ngsi-ld:cacheDuration", +
+
+    "containedBy": "ngsi-ld:isContainedBy", +
+
+    "contextSourceAlias": "ngsi-ld:contextSourceAlias", +
+
+    "contextSourceExtras": { +
+
+      "@id": "ngsi-ld:contextSourceExtras", +
+
+      "@type": "@json" +
+
+    }, +
+
+    "contextSourceInfo": "ngsi-ld:contextSourceInfo", +
+
+ "contextSourceTimeAt": { +
+
+      "@id": "ngsi-ld:contextSourceTimeAt", +
+
+      "@type": "DateTime" +
+
+},  +
+
+"contextSourceUptime": "ngsi-ld:contextSourceUptime", +
+
+    "cooldown": "ngsi-ld:cooldown", +
+
+    "coordinates": { +
+
+      "@container": "@list", +
+
+      "@id": "geojson:coordinates" +
+
+    }, +
+
+    "createdAt": { +
+
+      "@id": "ngsi-ld:createdAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "csf": "ngsi-ld:csf", +
+
+    "data": "ngsi-ld:data", +
+
+ "dataset": { +
+
+"@id": "ngsi-ld:hasDataset", +
+
+      "@container": "@index" +
+
+ }, +
+
+"datasetId": { +
+
+"@id": "ngsi-ld:datasetId", +
+
+"@type": "@id" +
+
+    }, +
+
+    "deletedAt": { +
+
+      "@id": "ngsi-ld:deletedAt", +
+
+      "@type": "DateTime" +
+
+    },  +
+
+    "description": "http://purl.org/dc/terms/description", +
+
+    "detail": "ngsi-ld:detail", +
+
+    "distinctCount": { +
+
+      "@id": "ngsi-ld:distinctCount", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "endAt": { +
+
+      "@id": "ngsi-ld:endAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "endTimeAt": { +
+
+      "@id": "ngsi-ld:endTimeAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "endpoint": "ngsi-ld:endpoint", +
+
+    "entities": "ngsi-ld:entities", +
+
+ "entity": "ngsi-ld:entity", +
+
+    "entityCount": "ngsi-ld:entityCount", +
+
+    "entityId": { +
+
+      "@id": "ngsi-ld:entityId", +
+
+      "@type": "@id" +
+
+    }, +
+
+ "entityList": { +
+
+      "@id": "ngsi-ld:entityList", +
+
+      "@container": "@list" +
+
+    }, +
+
+"entityMap": "ngsi-ld:hasEntityMap", +
+
+    "error": "ngsi-ld:error", +
+
+    "errors": "ngsi-ld:errors", +
+
+    "expiresAt": { +
+
+      "@id": "ngsi-ld:expiresAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "features": { +
+
+      "@container": "@set", +
+
+      "@id": "geojson:features" +
+
+    }, +
+
+    "format": "ngsi-ld:format", +
+
+    "geoQ": "ngsi-ld:geoQ", +
+
+    "geometry": "geojson:geometry", +
+
+    "geoproperty": "ngsi-ld:geoproperty", +
+
+    "georel": "ngsi-ld:georel", +
+
+    "idPattern": "ngsi-ld:idPattern", +
+
+    "information": "ngsi-ld:information", +
+
+    "instanceId": { +
+
+      "@id": "ngsi-ld:instanceId", +
+
+      "@type": "@id" +
+
+    }, +
+
+"isActive": "ngsi-ld:isActive", +
+
+"join": "ngsi-ld:join", +
+
+"joinLevel": "ngsi-ld:hasJoinLevel", +
+
+"json": { +
+
+  "@id": "ngsi-ld:hasJSON", "@type": "@json" +
+
+}, +
+
+"jsons": { +
+
+  "@id": "ngsi-ld:jsons", +
+
+  "@container": "@list" +
+
+}, +
+
+    "key": "ngsi-ld:hasKey", +
+
+ "lang": "ngsi-ld:lang", +
+
+ "languageMap": { +
+
+      "@id": "ngsi-ld:hasLanguageMap", +
+
+      "@container": "@language" +
+
+    }, +
+
+ "languageMaps": { +
+
+      "@id": "ngsi-ld:hasLanguageMaps", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "lastFailure": { +
+
+      "@id": "ngsi-ld:lastFailure", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "lastNotification": { +
+
+      "@id": "ngsi-ld:lastNotification", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "lastSuccess": { +
+
+      "@id": "ngsi-ld:lastSuccess", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "linkedMaps": "ngsi-ld:linkedMaps", +
+
+    "localOnly": "ngsi-ld:localOnly", +
+
+    "location": "ngsi-ld:location", +
+
+    "management": "ngsi-ld:management", +
+
+    "managementInterval": "ngsi-ld:managementInterval", +
+
+    "max": { +
+
+      "@id": "ngsi-ld:max", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "min": { +
+
+      "@id": "ngsi-ld:min", +
+
+      "@container": "@list" +
+
+    }, +
+
+ "mode": "ngsi-ld:mode", +
+
+    "modifiedAt": { +
+
+      "@id": "ngsi-ld:modifiedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "notification": "ngsi-ld:notification", +
+
+    "notificationTrigger": "ngsi-ld:notificationTrigger", +
+
+    "notifiedAt": { +
+
+      "@id": "ngsi-ld:notifiedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "notifierInfo": "ngsi-ld:notifierInfo", +
+
+    "notUpdated": "ngsi-ld:notUpdated", +
+
+    "object": { +
+
+      "@id": "ngsi-ld:hasObject", +
+
+      "@type": "@id" +
+
+    }, +
+
+ "objectList": { +
+
+      "@id": "ngsi-ld:hasObjectList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "objects": { +
+
+      "@id": "ngsi-ld:hasObjects", +
+
+      "@container": "@list" +
+
+    }, +
+
+ "objectsLists": { +
+
+      "@id": "ngsi-ld:hasObjectsLists", +
+
+      "@container": "@list" +
+
+    }, +
+
+ "objectType": { +
+
+      "@id": "ngsi-ld:hasObjectType", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "observationInterval": "ngsi-ld:observationInterval", +
+
+    "observationSpace": "ngsi-ld:observationSpace", +
+
+    "observedAt": { +
+
+      "@id": "ngsi-ld:observedAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "operationSpace": "ngsi-ld:operationSpace", +
+
+ "operations": "ngsi-ld:operations", +
+
+    "previousJson": { +
+
+      "@id": "ngsi-ld:hasPreviousJson", +
+
+      "@type": "@json" +
+
+    }, +
+
+ "previousLanguageMap": { +
+
+      "@id": "ngsi-ld:hasPreviousLanguageMap", +
+
+      "@container": "@language" +
+
+    }, +
+
+    "previousObject": { +
+
+      "@id": "ngsi-ld:hasPreviousObject", +
+
+      "@type": "@id" +
+
+    }, +
+
+ "previousObjectList": { +
+
+      "@id": "ngsi-ld:hasPreviousObjectList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "previousValue": "ngsi-ld:hasPreviousValue", +
+
+ "previousValueList": { +
+
+      "@id": "ngsi-ld:hasPreviousValueList", +
+
+      "@container": "@list" +
+
+    }, +
+
+ "previousVocab": { +
+
+      "@id": "ngsi-ld:hasPreviousVocab", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "properties": "geojson:properties", +
+
+    "propertyNames": { +
+
+      "@id": "ngsi-ld:propertyNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "q": "ngsi-ld:q", +
+
+    "reason": "ngsi-ld:reason", +
+
+ "receiverInfo": "ngsi-ld:receiverInfo", +
+
+ "refreshRate": "ngsi-ld:refreshRate", +
+
+ "registrationId": "ngsi-ld:registrationId", +
+
+    "registrationName": "ngsi-ld:registrationName", +
+
+    "relationshipNames": { +
+
+      "@id": "ngsi-ld:relationshipNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+ "scope": "ngsi-ld:scope", +
+
+ "scopeQ": "ngsi-ld:scopeQ", +
+
+ "showChanges": "ngsi-ld:showChanges", +
+
+    "startAt": { +
+
+      "@id": "ngsi-ld:startAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "status": "ngsi-ld:status", +
+
+    "stddev": { +
+
+      "@id": "ngsi-ld:stddev", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "subscriptionId": { +
+
+      "@id": "ngsi-ld:subscriptionId", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "subscriptionName": "ngsi-ld:subscriptionName", +
+
+    "success": { +
+
+      "@id": "ngsi-ld:success", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "sum": { +
+
+      "@id": "ngsi-ld:sum", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "sumsq": { +
+
+      "@id": "ngsi-ld:sumsq", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "sysAttrs": "ngsi-ld:sysAttrs", +
+
+    "temporalQ": "ngsi-ld:temporalQ", +
+
+ "tenant": { +
+
+      "@id": "ngsi-ld:tenant", +
+
+      "@type": "@id" +
+
+    }, +
+
+    "throttling": "ngsi-ld:throttling", +
+
+    "timeAt": { +
+
+      "@id": "ngsi-ld:timeAt", +
+
+      "@type": "DateTime" +
+
+    }, +
+
+    "timeInterval": "ngsi-ld:timeInterval", +
+
+    "timeout": "ngsi-ld:timeout", +
+
+    "timeproperty": "ngsi-ld:timeproperty", +
+
+    "timerel": "ngsi-ld:timerel", +
+
+    "timesFailed": "ngsi-ld:timesFailed", +
+
+    "timesSent": "ngsi-ld:timesSent", +
+
+ "title": "http://purl.org/dc/terms/title", +
+
+    "totalCount": { +
+
+      "@id": "ngsi-ld:totalCount", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "triggerReason": "ngsi-ld:triggerReason", +
+
+ "typeList": { +
+
+      "@id": "ngsi-ld:typeList", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "typeName": { +
+
+      "@id": "ngsi-ld:typeName", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "typeNames": { +
+
+      "@id": "ngsi-ld:typeNames", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "unchanged": "ngsi-ld:unchanged", +
+
+    "unitCode": "ngsi-ld:unitCode", +
+
+    "updated": "ngsi-ld:updated", +
+
+    "uri": "ngsi-ld:uri", +
+
+    "value": "ngsi-ld:hasValue", +
+
+ "valueList": { +
+
+      "@id": "ngsi-ld:hasValueList", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "valueLists": { +
+
+      "@id": "ngsi-ld:hasValueLists", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "values": { +
+
+      "@id": "ngsi-ld:hasValues", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "vocab": { +
+
+      "@id": "ngsi-ld:hasVocab", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+ "vocabs": { +
+
+      "@id": "ngsi-ld:hasVocabs", +
+
+      "@container": "@list" +
+
+    }, +
+
+    "watchedAttributes": { +
+
+      "@id": "ngsi-ld:watchedAttributes", +
+
+      "@type": "@vocab" +
+
+    }, +
+
+    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" +
+
+  } +
+
+} +
+
+ +
+
+NOTE: Implementers can take advantage of prefixed terms, i.e. in the form +ngsi-ld:term, to provide a terser representation of the Core +@context. +
+
+ + diff --git a/public/15-annex-c-informative-examples-of-using-the-api.html b/public/15-annex-c-informative-examples-of-using-the-api.html new file mode 100644 index 0000000000000000000000000000000000000000..d997517adf5bf73a7b60b2b64f0900f00dc9108f --- /dev/null +++ b/public/15-annex-c-informative-examples-of-using-the-api.html @@ -0,0 +1,12870 @@ + + + + + + + Annex C (informative): Examples of using the +API + + + + + + + + +

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

+

C.1 Introduction

+

This annex is informative and is intended to show in action the +JSON-LD representation defined by NGSI-LD.

+

JSON representations of the examples shown in this annex can be found +at [i.15].

+

C.2 Entity +Representation

+

C.2.1 Property +Graph

+

Figure +C.2.1‑1 shows a diagram representing a property graph to be used for +the examples discussed in this clause.

+
+ +
+
+Figure C.2.1-1: Reference example +
+

As per the algorithms described above and as per the rules for +generating the JSON-LD representation of NGSI-LD entities the above +graph will result in the following JSON-LD representations. The syntax +has been checked using the JSON-LD Playground tool [i.5].

+

C.2.2 Vehicle +Entity

+

Normalized Representation

+

The normalized representation is a lossless representation of an +Entity, where every Property is defined by a type and a +value and every Relationship is defined by a type +and an object.

+

Below there is a representation of an Entity of Type "Vehicle". It can be observed that the +@context is composed of different parts, namely the Core +@context and several vocabulary-specific @contexts.

+

It is noteworthy that the @context corresponding to the +Parking domain is included as it is referenced through the +isParked Relationship.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+    "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer", +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+
+ }, +
+
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+   "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+ ] +
+
+} +
+
+ +
+

Normalized Representation when inline Linked Entity retrieval +is used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned in an expanded format. Attributes of type "Relationship" are returned with an additional +entity sub-Attribute, which holds the normalized Linked Entity data corresponding to the +Relationship's target object URI. Attributes of +type "ListRelationship" are +returned with an additional entityList sub-Attribute which in +turn holds an ordered array of the normalized Linked Entities corresponding to the target +"objectList" URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+    "isParked": { +
+
+ "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+        "entity": { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": { +
+
+ "value": "Top Parking", +
+
+ "type": "Property" +
+
+ }, +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ "type": "Relationship" +
+
+ }, +
+
+  }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer", +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+ "objectType": "Person",  +
+
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+
+ "entity": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Alice", +
+
+ "type": "Property" +
+
+ } +
+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Bob", +
+
+ "type": "Property" +
+
+ } +
+
+ } +
+
+
+ ] +
+
+}, +
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ], +
+
+ "entityList": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Antwerp", +
+
+ "type": "Property" +
+
+ } +
+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Rotterdam", +
+
+ "type": "Property" +
+
+ } +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Amsterdam", +
+
+ "type": "Property" +
+
+ } +
+
+ } +
+
+
+ ] +
+
+}, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+
+ +
+

Normalized Representation when flattened Linked Entity +retrieval is used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of normalized Entities is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional normalized Linked Entity holding data corresponding to +the Relationship's target object URI is appended to the +array. For Attributes of type "ListRelationship", an array of normalized Linked Entities is appended, which hold the +data corresponding to each of the target URIs found within its +objectList.

+

[

+
+ { +
+
+     "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+     "type": "Vehicle", +
+
+     "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+     "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+ "tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "valueType": "Integer" +
+
+ "unitCode": "MMT" +
+
+ }, +
+
+ "passengers": { +
+
+   "type": "Relationship", +
+
+   "objectType": "Person", +
+
+   "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+ }, +
+
+ "route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+ }, +
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": { +
+
+ "value": "Top Parking", +
+
+ "type": "Property" +
+
+ }, +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ "type": "Relationship" +
+
+ }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Alice", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Bob", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Antwerp", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ +
+
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Rotterdam", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Amsterdam", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ } +
+
+] +
+
+ +
+

Normalized Representation when Language Filter is +used

+

When the Language Filter (see clause +4.15) is used, Properties of type "LanguageProperty" are returned as type "Property", and their languageMaps are +reduced to simple strings. For example if the language filter lang=fr is specified, only the value for French +language is present.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "Property", +
+
+ "value": "Grand Place", +
+
+ "lang": "fr" +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+    "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer", +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+    "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+}, +
+
+"@context": [ +
+
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+ ] +
+
+} +
+
+ +
+

Concise Representation

+

The concise representation is a terser, lossless form of the +normalized representation, where redundant Attribute type members +are omitted and the following rules are applied:

+
    +
  • +Every Property without further sub-attributes is represented +directly by the Property value only. +
    • +
  • +Every Property that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every GeoProperty without further sub-attributes is represented +by the GeoProperty's GeoJSON representation only. +
    • +
  • +Every GeoProperty that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every LanguageProperty is represented by a languageMap +key-value pair. +
    • +
  • +Every ListProperty is represented directly by the array of +Property values. +
    • +
  • +Every JsonProperty is represented by a json the value of +which is raw JSON which is not available for JSON-LD representation. +
    • +
  • +Every VocabProperty is represented by a vocab the value of +which is a compacted URI. +
    • +
  • +Every Relationship is represented by an object key-value pair. +
    • +
  • +Every ListRelationship is represented by an array of URIs. +
    • +
+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "street": { +
+
+        "languageMap": { +
+
+            "fr": "Grand Place", +
+
+            "nl": "Grote Markt" +
+
+        }  +
+
+    }, +
+
+    "isParked": { +
+
+        "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer" +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ] +
+
+
+ }, +
+
+
+"@context": [ +
+
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+
+ +
+

Concise Representation when inline Linked Entity retrieval is +used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned in an expanded format. The concise Linked Entity data corresponding to the +Relationship's target object URI is returned within an +entity sub-Attribute. Attributes of type "ListRelationship" are returned +within an entityList sub-Attribute which in turn holds an ordered +array of the Linked Entities in the +concise format corresponding to each of the targetobjectList +URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "street": { +
+
+        "languageMap": { +
+
+            "fr": "Grand Place", +
+
+            "nl": "Grote Markt" +
+
+        }  +
+
+    }, +
+
+    "isParked": { +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+        "entity": { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": "Top Parking", +
+
+ "operatedBy": { +
+
+ "object": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+     } +
+
+  }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer", +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+ "entity": [ +
+
+   { +
+
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": "Alice" +
+
+    }, +
+
+    { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": "Bob" +
+
+    } +
+
+
+ ] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ], +
+
+ "entityList": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+

"name": " Antwerp"

+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+

"name": "Rotterdam

+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+

"name": "Amsterdam"

+
+ } +
+
+
+ ] +
+
+}, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+
+ +
+

Concise Representation when flattened Linked Entity retrieval +is used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of concise Entities is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional concise Linked Entity holding data corresponding to +the Relationship's target object URI is appended to the +response. For Attributes of type "ListRelationship", an array of concise Linked Entities is appended to the response +which hold the data corresponding to each of the target URIs found +within its objectList.

+

[

+
+ { +
+
+     "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+     "type": "Vehicle", +
+
+     "brandName": "Mercedes", +
+
+     "street": { +
+
+         "languageMap": { +
+
+             "fr": "Grand Place", +
+
+             "nl": "Grote Markt" +
+
+         }  +
+
+     }, +
+
+        "isParked": {  +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+         "observedAt": "2017-07-29T12:00:04Z", +
+
+         "providedBy": { +
+
+             "object": "urn:ngsi-ld:Person:Bob" +
+
+         }  +
+
+     }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+ "tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "valueType": "Integer", +
+
+
+ +
+
+
+ "unitCode": "MMT" +
+
+ }, +
+
+ "passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+ }, +
+
+ "route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+   ] +
+
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": "Top Parking", +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": "Alice", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": "Bob", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": " Antwerp", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": "Rotterdam", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": "Amsterdam", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ } +
+
+] +
+
+ +
+

Concise representation when Language Filter is +used

+

The rules apply as defined in the previous examples. For example if +the language filter lang=fr is +specified.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "value": "Grand Place", +
+
+ "lang": "fr" +
+
+ }, +
+
+  "isParked": { +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+"valueType": "Integer", +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+   "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+   ] +
+
+}, +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Simplified Representation

+

The simplified representation is a collapsed, lossy representation of +an Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ } +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+"route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+], +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Simplified Representation when inline Linked Entity retrieval +is used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned as a JSON object holding key-value pairs corresponding to the +data from the Relationship's target object URI in +simplified format. Attributes of type "ListRelationship" are returned +as array of JSON objects each holding key-value pairs corresponding to +the data obtained from the target objectList URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ }, +
+
+   "isParked": { +
+
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": " OffStreetParking",   +
+
+
+ "name": "Top Parking", +
+
+ "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+ }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": [ +
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person",  +
+
+ "name": "Alice" +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person",  +
+
+ "name": "Bob" +
+
+ } +
+
+], +
+
+
+    "route": [ +
+
+
+   { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": " Antwerp" +
+
+     }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": "Rotterdam +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": "Amsterdam" +
+
+     } +
+
+    ], +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Simplified Representation when flattened Linked Entity retrieval is +used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of JSON Objects is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional JSON Object of +key-value pairs holding data corresponding to the Relationship's +target object URI is appended to the response. For Attributes of +type "ListRelationship", an array of JSON Objects each holding +key-value pairs corresponding to the data obtained from the target +objectList URIs is appended to the response.

+

[

+
+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ } +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+ "route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ], +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+}, +
+
+{ +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": " OffStreetParking",   +
+
+
+ "name": "Top Parking", +
+
+ "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+
+}, +
+
+{ +
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person",  +
+
+ "name": "Alice" +
+
+} +
+
+{ +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person",  +
+
+ "name": "Bob" +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+

"name": " Antwerp"

+
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+

"name": "Rotterdam

+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+

"name": "Amsterdam"

+
+} +
+
+] +
+
+ +
+

Simplified Representation of Natural Language +Attributes

+

The simplified natural language representation is a collapsed +representation of an Entity, which focuses on Property Values and +Relationship objects present at the first level of the graph, and where +languageMaps are reduced to simple string properties. For example +if the language filter lang=fr is +specified.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": "Grand Place", +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+"route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+], +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Multiple attribute example

+

Below is an example, where the speed of the car is provided by two +different sources. As both may be relevant at the same time, there are +two individual attribute instances for speed; each is identified by a +datasetId and both instances are represented in an array. The +datasetId enables individually creating, updating and deleting a +particular instance without affecting the instance from another +source.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "speed": [{ +
+
+    "type": "Property", +
+
+ "value": 55, +
+
+ "source": { +
+
+     "type": "Property", +
+
+ "value": "Speedometer" +
+
+ }, +
+
+ "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" +
+
+ }, +
+
+ { +
+
+    "type": "Property", +
+
+ "value": 54.5, +
+
+ "source": { +
+
+     "type": "Property", +
+
+ "value": "GPS" +
+
+ }, +
+
+ "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" +
+
+ }], +
+
+ "@context": [ +
+
+      { +
+
+ "Vehicle": "http://example.org/Vehicle", +
+
+ "speed": "http://example.org/speed", +
+
+      "source": "http://example.org/hasSource" +
+
+     }, +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

Simplified Representation of a multi-attribute

+

The simplified representation is a collapsed, lossy representation of +an Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "speed": { +
+
+ "dataset": { +
+
+ "urn:ngsi-ld:Property:speedometerA4567-speed": 55, +
+
+ "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5 +
+
+ } +
+
+ }, +
+
+ "@context": [ +
+
+      { +
+
+ "Vehicle": "http://example.org/Vehicle", +
+
+ "speed": "http://example.org/speed" +
+
+     }, +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

C.2.3 Parking +Entity

+

Normalized Representation

+

The normalized representation is a lossless representation of an +Entity, where every Property is defined by a type and a +value and every Relationship is defined by a type +and an object.

+

Below there is a representation of an Entity of Type "OffStreetParking". It can be observed that the +@context is composed of two different elements, the Core one and +the vocabulary-specific one.

+
+{ +
+
+   "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+   "type": "OffStreetParking", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Downtown One" +
+
+ }, +
+
+   "availableSpotNumber": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z", +
+
+     "reliability": { +
+
+       "type": "Property", +
+
+       "value": 0.7 +
+
+     }, +
+
+     "providedBy": { +
+
+        "type": "Relationship", +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+     } +
+
+ }, +
+
+ "totalSpotNumber": { +
+
+     "type": "Property", +
+
+     "value": 200 +
+
+ }, +
+
+ "location": { +
+
+ "type": "GeoProperty", +
+
+ "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.5, 41.2] +
+
+ } +
+
+ }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Concise Representation

+

The concise representation is a terser, lossless form of the +normalized representation, where redundant Attribute type members +are omitted and the following rules are applied:

+
    +
  • +Every Property without further sub-attributes is represented by +the Property value only. +
    • +
  • +Every Property that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every GeoProperty without further sub-attributes is represented +by the GeoProperty's GeoJSON representation only. +
    • +
  • +Every GeoProperty that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every LanguageProperty is defined by a languageMap +key-value pair. +
    • +
  • +Every VocabProperty is represented by a vocab the value of +which is a compacted URI. +
    • +
  • +Every Relationship is defined by an object key-value pair. +
    • +
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffStreetParking", +
+
+  "name": "Downtown One", +
+
+  "availableSpotNumber": { +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z", +
+
+    "reliability": 0.7, +
+
+    "providedBy": { +
+
+      "object": "urn:ngsi-ld:Camera:C1" +
+
+    } +
+
+  }, +
+
+  "totalSpotNumber": 200, +
+
+  "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [ +
+
+      -8.5, +
+
+      41.2 +
+
+    ] +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Simplified representation

+

The Simplified Representation (also known as "keyValues") is a lossy, collapsed representation of an +Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+    "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "type": "OffStreetParking", +
+
+ "name": "Downtown One", +
+
+    "availableSpotNumber": 121, +
+
+ "totalSpotNumber": 200, +
+
+ "location": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.5, 41.2] +
+
+ }, +
+
+ "@context": [ +
+
+     "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Normalized GeoJSON Representation

+

The normalized GeoJSON representation of a single Entity is defined +as a single GeoJSON Feature object as follows:

+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": { +
+
+      "type": "Property", +
+
+      "value": "Downtown One" +
+
+    }, +
+
+    "availableSpotNumber": { +
+
+      "type": "Property", +
+
+      "value": 121, +
+
+      "observedAt": "2017-07-29T12:05:02Z", +
+
+      "reliability": { +
+
+        "type": "Property", +
+
+        "value": 0.7 +
+
+      }, +
+
+      "providedBy": { +
+
+        "type": "Relationship", +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+      } +
+
+    }, +
+
+ "location": { +
+
+ "type": "GeoProperty", +
+
+ "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+ } +
+
+ }, +
+
+    "totalSpotNumber": { +
+
+      "type": "Property", +
+
+      "value": 200 +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+} +
+
+ +
+

The GeoJSON representation of multiple Entities is defined as a +GeoJSON FeatureCollection object containing an array of GeoJSON +features corresponding to the individual Entity representations.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.5, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": { +
+
+          "type": "Property", +
+
+          "value": "Downtown One" +
+
+        }, +
+
+        "availableSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 121, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+          }, +
+
+          "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 200 +
+
+        }, +
+
+ "location": { +
+
+   "type": "GeoProperty", +
+
+   "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+   } +
+
+ } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.51, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": { +
+
+          "type": "Property", +
+
+          "value": "Downtown Two" +
+
+        }, +
+
+        "availableSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 99, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.8 +
+
+          }, +
+
+          "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C2" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 100 +
+
+        }, +
+
+ "location": { +
+
+   "type": "GeoProperty", +
+
+   "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+   } +
+
+ } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Concise GeoJSON Representation

+

The concise GeoJSON representation of a single Entity is defined as a +single GeoJSON Feature object as follows:

+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [ +
+
+      -8.51, +
+
+      41.1 +
+
+    ] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": "Downtown One", +
+
+    "availableSpotNumber": { +
+
+      "value": 121, +
+
+      "observedAt": "2017-07-29T12:05:02Z", +
+
+      "reliability": 0.7, +
+
+      "providedBy": { +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+      } +
+
+    }, +
+
+    "location": { +
+
+      "type": "Point", +
+
+      "coordinates": [ +
+
+        -8.51, +
+
+        41.1 +
+
+      ] +
+
+    }, +
+
+    "totalSpotNumber": 200, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+} +
+
+ +
+

The concise GeoJSON representation of multiple Entities is defined as +a GeoJSON FeatureCollection object containing an array of GeoJSON +features corresponding to the individual Entity representations in +concise GeoJSON format.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [ +
+
+          -8.5, +
+
+          41.1 +
+
+        ] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown One", +
+
+        "availableSpotNumber": { +
+
+          "value": 121, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": 0.7, +
+
+          "providedBy": { +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": 200, +
+
+        "location": { +
+
+          "type": "Point", +
+
+          "coordinates": [ +
+
+            -8.51, +
+
+            41.1 +
+
+          ] +
+
+        } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [ +
+
+          -8.51, +
+
+          41.1 +
+
+        ] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown Two", +
+
+        "availableSpotNumber": { +
+
+          "value": 99, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": 0.8, +
+
+          "providedBy": { +
+
+            "object": "urn:ngsi-ld:Camera:C2" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": 100, +
+
+        "location": { +
+
+          "type": "Point", +
+
+          "coordinates": [ +
+
+            -8.51, +
+
+            41.1 +
+
+          ] +
+
+        } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Simplified GeoJSON Representation

+

The simplified GeoJSON representation of a single Entity is defined +as a single GeoJSON Feature object where the properties represent +a collapsed representation of the Entity, which focuses on Property +Values and Relationship objects present at the first level of the +graph.

+
+{ +
+
+  "id": "urn:ngsi-ld:offstreetparking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": "Downtown One", +
+
+    "availableSpotNumber": 121, +
+
+    "totalSpotNumber": 200, +
+
+    "location": { +
+
+   "type": "Point", +
+
+   "coordinates": [-8.51, 41.1] +
+
+ } +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

The simplified GeoJSON representation of multiple Entities is defined +as a GeoJSON FeatureCollection object containing an array of +GeoJSON features corresponding to the individual Entity representations +in simplified GeoJSON format.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.5, 41.2] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown One", +
+
+        "availableSpotNumber": 121, +
+
+        "totalSpotNumber": 200, +
+
+        "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.5, 41.2] +
+
+     } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.51, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown Two", +
+
+        "availableSpotNumber": 99, +
+
+        "totalSpotNumber": 100, +
+
+        "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+     } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+}   +
+
+ +
+

C.2.4 @context

+

The disposition of the @context can be as an inline JSON +object, as a dereferenceable URI or as a (multiple) combination of both. +In the examples above the @context is provided through several +dereferenceable URIs. The resulting @context (obtained by merging +the content of the resource referenced by the referred URIs) is shown +below.

+
+
+NOTE 1: +
+
+For + +brevity + +reasons + +the + +@context + +does + +not + +contain + +the + +API + +terms + +defined + +by + +clause +5.2 +. +
+
+
+
+NOTE 2: +
+
+Some + +extra + +terms + +are + +defined + +because + +they + +will + +be + +used + +in + +examples + +later + +presented. +
+
+
+{ +
+
+ "id": "@id", +
+
+ "type": "@type", +
+
+ "Property": "https://uri.etsi.org/ngsi-ld/Property", +
+
+ "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship", +
+
+ "value": "https://uri.etsi.org/ngsi-ld/hasValue", +
+
+ "object": { +
+
+ "@type": "@id", +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/hasObject" +
+
+ }, +
+
+ "observedAt": { +
+
+ "@type": "https://uri.etsi.org/ngsi-ld/DateTime", +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/observedAt" +
+
+ }, +
+
+ "datasetId": { +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/datasetId", +
+
+ "@type": "@id" +
+
+ }, +
+
+ "location": "https://uri.etsi.org/ngsi-ld/location", +
+
+ "GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty", +
+
+ "Vehicle": "http://example.org/vehicle/Vehicle", +
+
+ "street": "http://example.org/vehicle/street", +
+
+ "brandName": "http://example.org/vehicle/brandName", +
+
+ "category": "http://example.org/vehicle/category", +
+
+ "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths", +
+
+ "passengers": "http://example.org/vehicle/passengers", +
+
+ "speed": "http://example.org/vehicle/speed", +
+
+ "isParked": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/isParked" +
+
+ }, +
+
+ "OffStreetParking": "http://example.org/parking/OffStreetParking", +
+
+ "availableSpotNumber": "http://example.org/parking/availableSpotNumber", +
+
+ "totalSpotNumber": "http://example.org/parking/totalSpotNumber", +
+
+ "isNextToBuilding": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/isNextToBuilding" +
+
+ }, +
+
+ "reliability": "http://example.org/common/reliability",  +
+
+ "providedBy": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/providedBy" +
+
+ }, +
+
+ "name": "http://example.org/common/name", +
+
+ "commercial": +"http://example.org/vehicle/commercial", +
+
+ "non-commercial": "http://example.org/vehicle/non-commercial", +
+
+"Integer": "http://www.w3.org/2001/XMLSchema#Integer +
+
+} +
+
+ +
+

C.3 Context +Source Registration

+

Below there is an example representation of a Context Source Registration. It makes use +of the @context formerly described.

+
+{ +
+
+ "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456", +
+
+    "type": "ContextSourceRegistration", +
+
+    "information": [ +
+
+   { +
+
+ "entities": [  +
+
+ { +
+
+             "id": "urn:ngsi-ld:Vehicle:A456", +
+
+ "type": "Vehicle" +
+
+            } +
+
+ ], +
+
+ "propertyNames": ["brandName","speed"], +
+
+  "relationshipNames": ["isParked"] +
+
+   },  +
+
+   { +
+
+ "entities": [ +
+
+ { +
+
+             "idPattern": ".*downtown$", +
+
+ "type": "OffStreetParking" +
+
+            }, +
+
+ { +
+
+                "idPattern": ".*47$", +
+
+ "type": "OffStreetParking" +
+
+            } +
+
+ ], +
+
+ "propertyNames": ["availableSpotNumber","totalSpotNumber"], +
+
+ "relationshipNames": ["isNextToBuilding"] +
+
+      } +
+
+ ], +
+
+ "endpoint": "http://my.csource.org:1026", +
+
+ "location": { +
+
+ "type": "Polygon", +
+
+ "coordinates": [ +
+
+             [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], +
+
+               [100.0, 1.0], [100.0, 0.0]] ] +
+
+    }, +
+
+    "managementInterval": { +
+
+ "startAt": " 2017-11-29T14:53:15Z" +
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+

The Registration is referring to a Temporal Context Source capable of providing +temporal information from Entities of type "Vehicle" and "OffStreetParking", meeting certain id requirements. More +concretely, it can only provide the referenced Properties and +Relationships. Temporal information is provided for the given +managementInterval, i.e. related to createdAt and +modifiedAt Temporal Properties. The managementInterval is +specified as an open interval, so only a starting point is given. In +addition, the Registration example covers a particular geographical +area.

+

C.4 Context +Subscription

+

Below there is an example of a Context Subscription. It makes use of +the @context formerly described.

+
+{ +
+
+ "id": "urn:ngsi-ld:Subscription:mySubscription", +
+
+    "type": "Subscription", +
+
+    "entities": [ +
+
+ { +
+
+ "type": "Vehicle" +
+
+    } +
+
+ ], +
+
+    "watchedAttributes": ["speed"], +
+
+    "q": "speed>50", +
+
+    "geoQ": { +
+
+ "georel": "near;maxDistance==2000", +
+
+        "geometry": "Point", +
+
+        "coordinates": [-1,100] +
+
+    }, +
+
+    "notification": { +
+
+        "attributes": ["speed"], +
+
+        "format": "keyValues", +
+
+        "endpoint": { +
+
+           "uri": "http://my.endpoint.org/notify", +
+
+           "accept": "application/json" +
+
+        } +
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

The subject of the Context Subscription is Entities of Type +Vehicle which speed is greater than 50, and located close +to a certain area defined by a reference spatial point. Every time the +speed (watched Attribute) of a concerned vehicle, changes, a new +notification (including the new speed value) will be received in the +specified endpoint.

+

C.5 HTTP REST +API Examples

+

C.5.1 Introduction

+

This clause introduces some simple usage examples of the NGSI-LD API +(HTTP REST binding). They are not intended to be exhaustive but just a +sample for helping readers to understand better the present document. +ETSI ISG CIM published a Developer's Primer with many more examples, see +ETSI GR CIM 008 [i.21].

+

C.5.2 Create Entity of Type +Vehicle

+

C.5.2.1 HTTP +Request

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/ld+json +
+
+Content-Length: 556 +
+
+<Insert Here the JSON-LD representation of a Vehicle as described by +clause +C.2.2 Vehicle Entity> +
+

C.5.2.2 HTTP +Response

+
+201 Created +
+
+Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 +
+

C.5.3 Query +Entities

+

C.5.3.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +the + +Entities + +of + +type + +" +Vehicle +" + +whose + +brandName + +attribute + +is + +not + +"Mercedes" +. + +Only + +give + +back + +the + +brandName + +attribute + +and + +provide + +the + +data + +in + +the + +NGSI-LD + +Simplified + +Format. +
+
+

C.5.3.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=simplified +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.3.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Volvo", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.4 Query Entities +(Pagination)

+

C.5.4.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +the + +Entities + +of + +type + +"Vehicle" +. + +Only + +give + +back + +the + +brandName + +attribute + +and + +provide + +the + +data + +in + +the + +NGSI-LD + +Simplified + +Format. + +Limit + +the + +number + +of + +entities + +retrieved + +to + +2. +
+
+

C.5.4.2 HTTP +Request

+
+GET /ngsi-ld/v1/entities/?type= +Vehicle&format=simplified&limit=2 +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.4.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+Link: </ngsi-ld/v1/entities/?type= +Vehicle&format=simplified&limit=2&offset=2>; +rel="next"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Volvo", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A456", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.5 Temporal +Query

+

C.5.5.1 Introduction

+
+
+EXAMPLE 1: +
+
+Give + +back + +the + +temporal + +evolution + +of + +the + +attribute + +speed + +of + +Entities + +of + +type + +"Vehicle" + +whose + +brandName + +attribute + +is + +not + +"Mercedes" + +between + +the + +1 +st + +of + +August + +at + +noon + +and + +the + +1 +st + +of + +August + +at + +01 + +PM. +
+
+
+
+EXAMPLE 2: +
+
+Give + +back + +the + +temporal + +evolution + +of + +the + +attribute + +speed + +and + +brandName + +of + +Entities + +of + +type + +"Vehicle" + +whose + +brandName + +attribute + +is + +not + +"Mercedes" + +between + +the + +1 +st + +of + +August + +at + +noon + +and + +the + +1 +st + +of + +August + +at + +01 + +PM. + +As + +brandName + +attribute + +does + +not + +have + +any + +temporal + +evolution, + +brandName + +attribute + +is + +omitted + +in + +the + +response. +
+
+

C.5.5.2 HTTP +Request #1

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z +
+
+Accept: application/ld+json +
+
+Link: <http://example.org/ ngsi-ld +/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.5.3 HTTP +Response #1

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": [ +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 120, +
+
+        "observedAt": "2018-08-01T12:03:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 80, +
+
+        "observedAt": "2018-08-01T12:05:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 100, +
+
+        "observedAt": "2018-08-01T12:07:00Z" +
+
+      } +
+
+    ], +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+]  +
+
+ +
+
+

C.5.5.3 HTTP +Request #2

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z +
+
+Accept: application/ld+json +
+
+Link: <http://example.org/ ngsi-ld +/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.5.4 HTTP +Response #2

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": [ +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 120, +
+
+        "observedAt": "2018-08-01T12:03:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 80, +
+
+        "observedAt": "2018-08-01T12:05:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 100, +
+
+        "observedAt": "2018-08-01T12:07:00Z" +
+
+      } +
+
+    ], +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.6 Temporal +Query (Simplified Representation)

+

C.5.6.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +temporal + +evolution + +of + +the + +speed + +attribute + +for + +Entities + +of + +type + +"Vehicle" + +whose + +brandName + +attribute + +is + +not + +"Mercedes" + +between + +the + +1 +st + +of + +August + +at + +noon + +and + +the + +1 +st + +of + +August + +at + +01 + +PM. + +Simplified + +representation + +is + +required. +
+
+

C.5.6.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=temporalValues +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.6.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:03:00Z" +
+
+        ], +
+
+        [ +
+
+          80, +
+
+          "2018-08-01T12:05:00Z" +
+
+        ], +
+
+        [ +
+
+          100, +
+
+          "2018-08-01T12:07:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.7 Retrieve Available +Entity Types

+

C.5.7.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +entity + +types + +for + +which + +entity + +instances + +are + +currently + +available + +in + +the + +NGSI-LD + +system. +
+
+

C.5.7.2 HTTP +Request

+
+GET /ngsi-ld/v1/types +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.7.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:EntityTypeList:34534657", +
+
+  "type": "EntityTypeList", +
+
+  "typeList": [ +
+
+    "Vehicle", +
+
+    "OffStreetParking", +
+
+    "http://example.org/parking/ParkingSpot" +
+
+  ] +
+
+} +
+
+ +
+
+
+
+NOTE: +
+
+All + +entity + +types + +that + +can + +be + +found + +in + +the + +provided + +@context + +are + +given + +as + +short + +names, + +the + +others + +as + +Fully + +Qualified + +Names + +(FQNs). +
+
+

C.5.8 Retrieve +Details of Available Entity Types

+

C.5.8.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +details + +of + +all + +entity + +types + +for + +which + +entity + +instances + +are + +currently + +available + +in + +the + +NGSI-LD + +system. +
+
+

C.5.8.2 HTTP +Request

+
+GET /ngsi-ld/v1/types?details=true +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.8.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "http://example.org/vehicle/Vehicle", +
+
+    "type": "EntityType", +
+
+    "typeName": "Vehicle", +
+
+    "attributeNames": [ +
+
+      "brandName", +
+
+      "isParked", +
+
+      "location", +
+
+      "speed" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/OffStreetParking", +
+
+    "type": "EntityType", +
+
+    "typeName": "OffStreetParking", +
+
+    "attributeNames": [ +
+
+      "availableSpotNumber", +
+
+      "isNextToBuilding", +
+
+      "location", +
+
+      "totalSpotNumber" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/ParkingSpot", +
+
+    "type": "EntityType", +
+
+    "typeName": "http://example.org/parking/ParkingSpot", +
+
+    "attributeNames":[ +
+
+      "location", +
+
+      "http://example.org/parking/status" +
+
+    ] +
+
+  } +
+
+]  +
+
+ +
+
+
+
+NOTE: +
+
+The + +type + +name + +of + +all + +entity + +types + +and + +all + +attribute + +names + +that + +can + +be + +found + +in + +the + +provided + +@context + +are + +given + +as + +short + +names, + +the + +others + +as + +Fully + +Qualified + +Names + +(FQNs). + +The + +id + +is + +always + +an + +FQN. +
+
+

C.5.9 Retrieve +Available Entity Type Information

+

C.5.9.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +details + +of + +entity + +type + +"Vehicle" + +(for + +which + +entity + +instances + +are + +currently + +available + +in + +the + +NGSI-LD + +system). +
+
+

C.5.9.2 HTTP +Request

+
+GET /ngsi-ld/v1/types/Vehicle +
+
+[Alternative with FQN: GET +/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle] +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.9.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "http://example.org/vehicle/Vehicle", +
+
+  "type": "EntityTypeInfo", +
+
+  "typeName": "Vehicle", +
+
+  "entityCount": 2, +
+
+  "attributeDetails": [ +
+
+    { +
+
+      "id": "http://example.org/vehicle/brandName", +
+
+      "type": "Attribute", +
+
+      "attributeName": "brandName", +
+
+      "attributeTypes": [ +
+
+        "Property" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "http://example.org/vehicle/isParked", +
+
+      "type": "Attribute", +
+
+      "attributeName": "isParked", +
+
+      "attributeTypes": [ +
+
+        "Relationship" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "https://uri.etsi.org/ngsi-ld/location", +
+
+      "type": "Attribute", +
+
+      "attributeName": "location", +
+
+      "attributeTypes": [ +
+
+        "GeoProperty" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "http://example.org/vehicle/speed", +
+
+      "type": "Attribute", +
+
+      "attributeName": "speed", +
+
+      "attributeTypes": [ +
+
+        "Property" +
+
+      ] +
+
+    } +
+
+  ] +
+
+} +
+
+ +
+
+

C.5.10 Retrieve Available +Attributes

+

C.5.10.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +attribute + +names + +for + +which + +entity + +instances + +are + +currently + +available + +in + +the + +NGSI-LD + +system + +that + +have + +an + +attribute + +with + +the + +respective + +name. +
+
+

C.5.10.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.10.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:AttributeList:56534657", +
+
+  "type": "AttributeList", +
+
+  "attributeList": [ +
+
+    "brandName", +
+
+    "isParked", +
+
+    "location", +
+
+    "speed", +
+
+    "http://example.org/parking/status" +
+
+  ] +
+
+} +
+
+ +
+
+
+
+NOTE: +
+
+The + +attribute + +names + +that + +can + +be + +found + +in + +the + +provided + +@context + +are + +given + +as + +short + +names, + +the + +others + +as + +fully + +qualified + +names + +(FQNs). +
+
+

C.5.11 Retrieve +Details of Available Attributes

+

C.5.11.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +details + +of + +all + +attributes + +for + +which + +entity + +instances + +are + +currently + +available + +in + +the + +NGSI-LD + +system + +to + +which + +an + +attribute + +with + +the + +respective + +attribute + +name + +belongs. +
+
+

C.5.11.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes?details=true +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.11.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "http://example.org/vehicle/brandName", +
+
+    "type": "Attribute", +
+
+    "attributeName": "brandName", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/vehicle/isParked", +
+
+    "type": "Attribute", +
+
+    "attributeName": "isParked", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "https://uri.etsi.org/ngsi-ld/location", +
+
+    "type": "Attribute", +
+
+    "attributeName": "location", +
+
+    "typeNames": [ +
+
+      "Vehicle", +
+
+      "OffStreetParking", +
+
+      "http://example.org/parking/ParkingSpot" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/vehicle/speed", +
+
+    "type": "Attribute", +
+
+    "attributeName": "speed", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/status", +
+
+    "type": "Attribute", +
+
+    "attributeName": "http://example.org/parking/status", +
+
+    "typeNames": [ +
+
+      "http://example.org/parking/ParkingSpot" +
+
+    ] +
+
+  } +
+
+]  +
+
+ +
+
+
+
+NOTE: +
+
+The + +attribute + +name + +and + +all + +type + +names + +that + +can + +be + +found + +in + +the + +provided + +@context + +are + +given + +as + +short + +names, + +the + +others + +as + +Fully + +Qualified + +Names + +(FQNs). + +The + +id + +is + +always + +an + +FQN. +
+
+

C.5.12 Retrieve +Available Attribute Information

+

C.5.12.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +details + +of + +the + +attribute + +named + +brandName + +(for + +which + +entity + +instances + +with + +an + +attribute + +of + +this + +name + +are + +currently + +available + +in + +the + +NGSI-LD + +system). +
+
+

C.5.12.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes/brandName +
+
+[Alternative with FQN: GET +/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName] +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.12.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "http://example.org/vehicle/brandName", +
+
+  "type": "Attribute", +
+
+  "attributeName": "brandName", +
+
+  "attributeTypes": ["Property"], +
+
+  "typeNames": ["Vehicle"], +
+
+  "attributeCount": 2 +
+
+} +
+
+ +
+
+

C.5.13 Query +Entities (Natural Language Filtering)

+

C.5.13.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +the + +Entities + +of + +type + +"Vehicle" + +where + +the + +marque + +attribute + +in + +British + +English + +is + +"Vauxhall Viva" +. + +Only + +give + +back + +the + +marque + +attribute + +and + +provide + +the + +data + +in + +the + +NGSI-LD + +Simplified + +Format + +and + +only + +return + +language + +strings + +in + +German. +
+
+

C.5.13.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]== +"Vauxhall Viva"&format =simplified&lang=de +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.13.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "marque": "Opel Karl", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.14 Temporal +Query (Aggregated Representation)

+

C.5.14.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +maximum + +and + +average + +speed + +of + +Entities + +of + +type + +"Vehicle" + +whose + +brandName + +attribute + +is + +not + +"Mercedes" + +between + +the + +1 +st + +of + +August + +at + +noon + +and + +the + +1 +st + +of + +August + +at + +01 + +PM, + +aggregated + +by + +periods + +of + +4 + +minutes. +
+
+

C.5.14.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=aggregatedValues +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.14.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "max": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:00:00Z", +
+
+          "2018-08-01T12:04:00Z" +
+
+        ], +
+
+        [ +
+
+          100, +
+
+          "2018-08-01T12:04:00Z", +
+
+          "2018-08-01T12:08:00Z" +
+
+        ] +
+
+      ], +
+
+      "avg": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:00:00Z", +
+
+          "2018-08-01T12:04:00Z" +
+
+        ], +
+
+        [ +
+
+          90, +
+
+          "2018-08-01T12:04:00Z", +
+
+          "2018-08-01T12:08:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.15 Scope +Queries

+

C.5.15.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +all + +the + +Entities + +of + +type + +" +OffStreetParking +" + +that + +are + +within + +the + +Scope + +/Madrid/Centro + +or + +/Madrid/Cortes +. +
+
+

C.5.15.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes" +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.15.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+   { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "OffStreetParking", +
+
+      "scope": "/Madrid/Centro", +
+
+      "name": { +
+
+         "type": "Property", +
+
+         "value": "Downtown One" +
+
+      }, +
+
+      "availableSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 121, +
+
+         "observedAt": "2017-07-29T12:05:02Z", +
+
+         "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+         }, +
+
+         "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+         } +
+
+      }, +
+
+      "totalSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 200 +
+
+      }, +
+
+      "location": { +
+
+         "type": "GeoProperty", +
+
+         "value": { +
+
+            "type": "Point", +
+
+            "coordinates": [ +
+
+               -8.5, +
+
+               41.2 +
+
+            ] +
+
+         } +
+
+      }, +
+
+      "@context": [ +
+
+         "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+      ] +
+
+   }, +
+
+   { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Corte4", +
+
+      "type": "OffStreetParking", +
+
+      "scope": [ +
+
+            "/Madrid/Cortes", +
+
+            "/Company894/UnitC" +
+
+      ], +
+
+      "name": { +
+
+         "type": "Property", +
+
+         "value": "Corte4" +
+
+      }, +
+
+      "availableSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 121, +
+
+         "observedAt": "2017-07-29T12:05:02Z", +
+
+         "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+         }, +
+
+         "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+         } +
+
+      }, +
+
+      "totalSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 100 +
+
+      }, +
+
+      "location": { +
+
+         "type": "GeoProperty", +
+
+         "value": { +
+
+            "type": "Point", +
+
+            "coordinates": [ +
+
+               -8.6, +
+
+               41.3 +
+
+            ] +
+
+         } +
+
+      }, +
+
+      "@context": [ +
+
+         "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+      ] +
+
+   } +
+
+] +
+
+ +
+
+

C.5.16 Temporal Scope Queries

+

C.5.16.1 Introduction

+
+
+EXAMPLE: +
+
+Give + +back + +the + +speed + +of + +all + +the + +Entities + +of + +type + +"Vehicle" + +that + +have + +been + +within + +the + +Scope + +/Madrid/Centro + +between + +the + +1 +st + +of + +August + +2018 + +at + +noon + +and + +the + +1 +st + +of + +August + +2018 + +at + +01 + +PM. + +Note + +that + +the + +value + +of + +the + +Scope + +has + +to + +match + +for + +the + +given + +timeframe, + +which + +means + +it + +is + +possible + +that + +it + +has + +been + +set + +before, + +e.g. + +on + +1 +st + +of + +August + +2018 + +at + +11 + +AM. +
+
+

C.5.16.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro" +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.16.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "scope": { +
+
+  "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          "/Madrid/Centro", +
+
+          "2018-08-01T11:00:00Z" +
+
+        ] +
+
+  ] +
+
+    }, +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          30, +
+
+          "2018-08-01T12:03:00Z" +
+
+        ], +
+
+        [ +
+
+          60, +
+
+          "2018-08-01T12:05:00Z" +
+
+        ], +
+
+        [ +
+
+          50, +
+
+          "2018-08-01T12:07:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A8311", +
+
+    "type": "Vehicle", +
+
+    "scope": { +
+
+  "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          [ +
+
+             "/Madrid/Centro", +
+
+             "/Company123/UnitA" +
+
+          ], +
+
+          "2018-08-01T12:10:00Z" +
+
+        ] +
+
+  ] +
+
+    }, +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          40, +
+
+          "2018-08-01T12:12:00Z" +
+
+        ], +
+
+        [ +
+
+          60, +
+
+          "2018-08-01T12:14:00Z" +
+
+        ], +
+
+        [ +
+
+          50, +
+
+          "2018-08-01T12:16:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

Vehicle B9211 has already been within +the Scope /Madrid/Centro before the +beginning of the request interval, whereas Vehicle A8311 only entered the Scope within the request +interval. Thus in the latter case only Property values are included that +have been observed after the Scope has become valid.

+

C.6 Date +Representation

+

In NGSI-LD, a TemporalProperty is represented only by its +value, i.e. no sub-Properties of TemporalProperty nor +sub-Relationships of TemporalProperty can be conveyed. In more +formal language, a TemporalProperty does not allow reification. +The term TemporalProperty has been reserved for non-reified +structural timestamps (observedAt, createdAt, +modifiedAt, deletedAt), which capture the temporal +evolution of Attributes. Only such structural timestamps can be used as +timeproperty in Temporal Queries as mandated by clause +4.11.

+

The following examples show how time values (Date, +Time, or DateTime) can be represented in NGSI-LD as +reified Properties. For a reified Property whose value is assigned the +JSON type Date, DateTime or Time, one mechanism is to use the +Property’s valueType to hold the datatype ("Date", "Datetime" or +"Time"), as shown below:

+
+{ +
+
+"id": "urn:ngsi-ld:Vehicle:B9211", +
+
+"type": "Vehicle", +
+
+"testedAt": { +
+
+"type": "Property", +
+
+"value":"2018-12-04T12:00:00Z" +
+
+"valueType": "DateTime" +
+
+}, +
+
+"@context": [ +
+
+"http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+] +
+
+} +
+

Alternatively the data can be a structured to use the JSON-LD +@value syntax structure, as shown below:

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+  "type": "Vehicle", +
+
+  "testedAt": { +
+
+    "type": "Property", +
+
+    "value": { +
+
+      "@type": "DateTime", +
+
+      "@value": "2018-12-04T12:00:00Z" +
+
+    } +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

A third alternative to achieve the same result would be to use +JSON-LD “type coercion”. With type coercion, values with a special data +type are defined with @type in the @context. This enforces +the correct type for any occurrence. Such an @context fragment is +shown below:

+
+"testedAt": { +
+
+  "@type": "https://uri.etsi.org/ngsi-ld/DateTime", +
+
+  "@id": "http://example.org/test/testedAt" +
+
+} +
+
+ +
+

The above does not work, when using the @context to perform +compaction, in the normalized and compact representation of NGSI-LD, due +to reification of the Property, because in this case testedAt is +a complex JSON object, which cannot be compacted to a DateTime +type as the @context specifies. Thus, the full URI +http://example.org/test/testedAt is kept, instead of the short +name testedAt. In summary, user @contexts used for the +normalized and compact NGSI-LD representation cannot use the JSON-LD +type coercion feature.

+

However, in the simplified (keyValue) representation case, such an +@context with the specification of testedAt could be used, +as there is no reification.

+

As a side note, when using the above @value + @type +approach, since type is mapped to @type in the NGSI-LD +core @context, JSON-LD compaction will result in the following +compacted value, instead of the one shown above, because @type is +compacted to type:

+
+"value": { +
+
+  "type": "DateTime", +
+
+  "@value": "2018-12-04T12:00:00Z" +
+
+} +
+
+ +
+

C.7 @context utilization +clarifications

+

When expanding or compacting JSON-LD terms, the JSON-LD +@context to be used is always the one provided in the current API +request. For the benefit of users and implementers the following +examples illustrate this concept.

+

The scenario starts with the creation of an Entity using a JSON-LD +@context as follows:

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/ld+json +
+
+Content-Length: 200 +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffStreetParking", +
+
+  "name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "availableSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "totalSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 200 +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+
+ +
+

The content of the @context utilized for the referred Entity +creation (at http://example.org/ngsi-ld/latest/parking.jsonld) is as +follows:

+
+{ +
+
+
+"OffStreetParking": "http://example.org/parking/OffStreetParking", +
+
+"availableSpotNumber": "http://example.org/parking/availableSpotNumber", +
+
+"totalSpotNumber": "http://example.org/parking/totalSpotNumber", +
+
+"name": "http://example.org/parking/name" +
+
+
+} +
+
+ +
+

At Entity creation time the implementation will perform the expansion +of terms using the JSON-LD @context depicted above.

+

Now it is needed to retrieve our initial Entity. For retrieving such +Entity, this time, a different JSON-LD @context is going to be +utilized, as follows:

+
+{ +
+
+
+"OffP": "http://example.org/parking/OffStreetParking", +
+
+"ava": "http://example.org/parking/availableSpotNumber", +
+
+"total": "http://example.org/parking/totalSpotNumber" +
+
+
+} +
+
+ +
+

This new @context, even though it makes use of the same set of +Fully Qualified Names, is defining new short strings as terms. The +reasons for that could be multiple: to facilitate data consumption by +clients, to save some bandwidth, to enable a more (or less) +human-readable response payload body in a language different than +English, etc.

+

In this particular case, the result of the Entity retrieval will be +as depicted below. It can be observed that the terms defined by the +JSON-LD @context provided at retrieval time are +used to render the Entity content (compaction), and not +the terms that were provided at creation time (which may be no longer +known by the broker).

+

It is also interesting to note that the @context array of the +response payload body contains, indeed, our header-supplied +@context:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffP", +
+
+  "name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "ava": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "total": { +
+
+  "type": "Property", +
+
+    "value": 200 +
+
+ }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+
+ +
+
+Another interesting case to note is the one when an @context with +no matching terms or no @context at all is supplied. See the +following example: +
+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 +
+
+Accept: application/ld+json +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "http://example.org/parking/OffStreetParking", +
+
+  "http://example.org/parking/name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "http://example.org/parking/availableSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "http://example.org/parking/totalSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 200 +
+
+  }, +
+
+  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+} +
+
+
+ +
+

In this particular case it can be observed that the user names +(Entity Type, Attributes) in the response payload body have not been +compacted, and as a result the Fully Qualified Names are included. +However, the core API terms have been compacted, as the Core +@context is always considered to be implicitly present if not +specified explicitly (and that is why it is included in the JSON-LD +response, as mandated by the specification).

+

C.8 Link header +utilization clarifications

+

The JSON-LD Specification [2] states clearly that +only one HTTP Link header with the link relationship +<http://www.w3.org/ns/json-ld#context> is required to appear. Such +statement has implications in terms of providing the JSON-LD +@context when using the NGSI-LD API. The main implication is that +if the @context is a compound one, i.e. an @context which +references multiple individual @context, served by resources +behind different URIs, then a wrapper @context +has to be created and hosted. The final aim is that only one +@context is referenced from the JSON-LD Link header. This can be +illustrated with an example:

+

Imagine that it is desired to create an Entity providing +@context terms which are defined in two different JSON-LD +@context resources:

+
    +
  • +http://example.org/vehicle/v1/vehicle-context.jsonld +
    • +
  • +https://schema.org +
    • +
+

If a developer wants to reference these two @context resources +from a Link header, a wrapper @context can be easily created as +follows:

+
+{ +
+
+   "@context": [ +
+
+       "http://example.org/vehicle/v1/vehicle-context.jsonld", +
+
+       "https://schema.org", +
+
+       "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

As such wrapper @context needs to be referenced from a Link header by +using a URI, then it will have to be hosted at some place on the Web. +Usually, developers will host @context using popular and simple +solutions such as GitHub or GitLab pages. As a result, developers will +be able to use @context in queries or when using "application/json" as main content type managed +by their applications.

+

It is a good practice to include the Core +@context in the wrapper @context so it can be used, +off-the-shelf, by external JSON-LD processing tools. However, it should +be noted this is not necessary for NGSI-LD, as the Core @context +is always implicitly included.

+

Then, using such wrapper @context, (in our example hosted at +https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), +the developer will be able to issue requests like:

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/json +
+
+Content-Length: 200 +
+
+Link: +<https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+{ +
+
+   "id": "urn:ngsi-ld:Vehicle:V1", +
+
+   "type": "Vehicle", +
+
+ "builtYear": { +
+
+ "type": "Property", +
+
+     "value": "2014" +
+
+ }, +
+
+   "speed": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z" +
+
+ } +
+
+} +
+
+ +
+
+201 Created +
+
+Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 +
+
+Link: < https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld +>; rel="http://www.w3.org/ns/json-ld#context"; +type="application/ld+json" +
+
+GET /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 +
+
+Accept: application/ld+json +
+
+Link: +<https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+200 OK +
+
+Content-Type: application/ld+json +
+
+{ +
+
+   "id": "urn:ngsi-ld:Vehicle:V1", +
+
+   "type": "Vehicle", +
+
+ "builtYear": { +
+
+ "type": "Property", +
+
+     "value": "2014" +
+
+ }, +
+
+   "speed": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z" +
+
+ }, +
+
+    "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld" +
+
+} +
+
+ +
+

Observe that in this case the broker is responding with the same +wrapper @context in the Link header of the HTTP Response or +within the JSON-LD response payload body (when MIME type accepted is +"application/ld+json"). However, that +could not be always the case, as there could be situations where the +broker could need to provide a wrapper @context hosted by itself, +for instance, when there are inline @context terms or when the +Core @context has not been previously included by the wrapper +@context (not recommended) provided within developer's +requests.

+

C.9 @context processing +clarifications

+

JSON-LD Specification [2] says that "If a term is +redefined within a context, all previous rules associated with the +previous definition are removed". In addition, it is stated that +"Multiple contexts may be combined using an array, which is processed in +order".

+

In contrast to the JSON-LD Specification, the NGSI-LD specification +states that the Core @context is protected and has to remain +immutable. This essentially means that the Core @context has +final precedence and, therefore, is always to be processed as the last +one in the @context array. For clarity, data providers should +place the Core @context in the final position. From the point of +view of Data providers, care has to be taken so that there are no +unexpected or undesired term expansions. See the following example:

+
+{ +
+
+   "id": "urn:ngsi-ld:Building:B1", +
+
+   "type": "Building", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Empire State" +
+
+ }, +
+
+   "location": { +
+
+     "type": "Property", +
+
+     "value": "20 West 34th Street, New York City, NY 10001" +
+
+ }, +
+
+    "@context": [ +
+
+        "https://schema.org/version/latest/schemaorg-current-https.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+

The problem of the example above is that the term "location" is defined in both the Core @context +and the schema.org user @context and the Core @context +takes precedence for the expansion. In these situations, if one wanted +to refer to the schema.org "location", +the solution is to prefix the conflicting terms, so that there cannot be +any clashing. Therefore, if the intent is to refer to https://schema.org/location +throughout, the example above can be modified as shown below:

+
+{ +
+
+   "id": "urn:ngsi-ld:Building:B1", +
+
+   "type": "Building", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Empire State" +
+
+ }, +
+
+   "schema:location": { +
+
+     "type": "Property", +
+
+     "value": "20 West 34th Street, New York City, NY 10001" +
+
+ }, +
+
+    "@context": [ +
+
+        "https://schema.org/version/latest/schemaorg-current-https.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+
+Note that the Core @context should be placed in the last position +of the @context array. NGSI-LD implementations are required to +render content following this approach, which has been undertaken in +order to maximize compatibility with JSON-LD processing tools. This +example works because the "schema:" +prefix has already been defined by the schema.org @context. +
+

C.10 ValueType +datatype utilization clarifications

+
+Using JSON-LD [2] +syntax, typed values can be expressed using the JSON-LD @type +keyword when defining a term, where @type value holds a URI which +indicates the value’s datatype. However, it can be desirable for a +Context Broker to be able to hold simpler untyped values within a +Property’s value attribute and separately use a Property’s +valueType to hold the value’s datatype. This format can be used +to accommodate multiple acceptable datatype formats for the data to be +held within a single Property and still hold sufficient meta data to be +able to distinguish between them. +
+
+For example, consider an ontology for an Entity of type "Place" which +has an address Property, where the address Property can +either be an unstructured address in the form of a +"String" or a structured "PostalAddress" JSON Object +with street, city and country attributes – the +following JSON-LD schema can be defined: +
+

Example JSON-LD schema

+
+{ +
+
+"example": "http://example.org/", +
+
+"xsd": "http://www.w3.org/2001/XMLSchema#", +
+
+"address": "example:address", +
+
+"city": "example:city", +
+
+"country": "example:country", +
+
+"street": "example:street", +
+
+"Place": "example:Place" +
+
+"PostalAddress": "example:PostalAddress", +
+
+"String": "xsd:String" +
+
+} +
+
+ +
+
+Then the following two Entities of type "Place"can be created using the +address.valueType Property to distinguish between the two +formats: +
+
+[ +
+
+{ +
+
+"id": "urn:ngsi-ld:Place:27182", +
+
+"type": "Place", +
+
+"address": { +
+
+"type": "Property", +
+
+"value": "Pariser Platz, Berlin, Germany", +
+
+"valueType": "String" +
+
+        } +
+
+}, +
+
+{ +
+
+"id": "urn:ngsi-ld:Place:31415", +
+
+"type": "Place", +
+
+"address": { +
+
+"type": "Property", +
+
+"value": { +
+
+        "street": "Straße des 17. +Juni", +
+
+        "city": "Berlin", +
+
+        "country": "Germany" +
+
+   },
+   "valueType": "PostalAddress" +
+
+   } +
+
+   } +
+
+] +
+ + diff --git a/public/16-annex-c-informative-examples-of-using-the-api.html b/public/16-annex-c-informative-examples-of-using-the-api.html new file mode 100644 index 0000000000000000000000000000000000000000..6ce011d93c0495249621c79ed58495b964a369ee --- /dev/null +++ b/public/16-annex-c-informative-examples-of-using-the-api.html @@ -0,0 +1,11693 @@ + + + + + + + Annex C (informative): Examples of using the API + + + + + + + +
+

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

+

C.1 Introduction

+

This annex is informative and is intended to show in action the +JSON-LD representation defined by NGSI-LD.

+

JSON representations of the examples shown in this annex can be found +at [i.15].

+

C.2 Entity +Representation

+

C.2.1 Property +Graph

+

Figure +C.2.1‑1 shows a diagram representing a property graph to be used for +the examples discussed in this clause.

+
+ +
+
+Figure C.2.1-1: Reference example +
+

As per the algorithms described above and as per the rules for +generating the JSON-LD representation of NGSI-LD entities the above +graph will result in the following JSON-LD representations. The syntax +has been checked using the JSON-LD Playground tool [i.5].

+

C.2.2 Vehicle +Entity

+

Normalized Representation

+

The normalized representation is a lossless representation of an +Entity, where every Property is defined by a type and a +value and every Relationship is defined by a type +and an object.

+

Below there is a representation of an Entity of Type "Vehicle". It can be observed that the +@context is composed of different parts, namely the Core +@context and several vocabulary-specific @contexts.

+

It is noteworthy that the @context corresponding to the +Parking domain is included as it is referenced through the +isParked Relationship.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+    "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+
+ }, +
+
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+   "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+ ] +
+
+} +
+
+ +
+

Normalized Representation when inline Linked Entity retrieval +is used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned in an expanded format. Attributes of type "Relationship" are returned with an additional +entity sub-Attribute, which holds the normalized Linked Entity data corresponding to the +Relationship's target object URI. Attributes of +type "ListRelationship" are +returned with an additional entityList sub-Attribute which in +turn holds an ordered array of the normalized Linked Entities corresponding to the target +"objectList" URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+    "isParked": { +
+
+ "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+        "entity": { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": { +
+
+ "value": "Top Parking", +
+
+ "type": "Property" +
+
+ }, +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ "type": "Relationship" +
+
+ }, +
+
+  }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+ "objectType": "Person",  +
+
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+
+ "entity": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Alice", +
+
+ "type": "Property" +
+
+ } +
+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Bob", +
+
+ "type": "Property" +
+
+ } +
+
+ } +
+
+
+ ] +
+
+}, +
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ], +
+
+ "entityList": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Antwerp", +
+
+ "type": "Property" +
+
+ } +
+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Rotterdam", +
+
+ "type": "Property" +
+
+ } +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Amsterdam", +
+
+ "type": "Property" +
+
+ } +
+
+ } +
+
+
+ ] +
+
+}, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+

Normalized Representation when flattened Linked Entity +retrieval is used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of normalized Entities is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional normalized Linked Entity holding data corresponding to +the Relationship's target object URI is appended to the +array. For Attributes of type "ListRelationship”, an array of normalized Linked Entities is appended, which hold the +data corresponding to each of the target URIs found within its +objectList.

+

[

+
+ { +
+
+     "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+     "type": "Vehicle", +
+
+     "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "LanguageProperty", +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt +
+
+ }  +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+     "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+ "tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+ }, +
+
+ "passengers": { +
+
+   "type": "Relationship", +
+
+   "objectType": "Person", +
+
+   "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+ }, +
+
+ "route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+ }, +
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": { +
+
+ "value": "Top Parking", +
+
+ "type": "Property" +
+
+ }, +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ "type": "Relationship" +
+
+ }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Alice", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": { +
+
+ "value": "Bob", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Antwerp", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ +
+
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Rotterdam", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": { +
+
+ "value": "Amsterdam", +
+
+ "type": "Property" +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ } +
+
+] +
+
+ +
+

Normalized Representation when Language Filter is +used

+

When the Language Filter (see clause +4.15) is used, Properties of type "LanguageProperty" are returned as type "Property", and their languageMaps are +reduced to simple strings. For example if the language filter lang=fr is specified, only the value for French +language is present.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": { +
+
+    "type": "Property", +
+
+ "value": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "type": "Property", +
+
+ "value": "Grand Place", +
+
+ "lang": "fr" +
+
+ }, +
+
+  "isParked": { +
+
+    "type": "Relationship", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "type": "Relationship", +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+    "category": { +
+
+    "type": "VocabularyProperty", +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "type": "ListProperty", +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "type": "Relationship", +
+
+    "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "type": "ListRelationship", +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   {"object": "urn:ngsi-ld:City:Antwerp"}, +
+
+ {"object": "urn:ngsi-ld:City:Rotterdam"} +
+
+   {"object": "urn:ngsi-ld:City:Amsterdam"} +
+
+   ] +
+
+}, +
+
+"@context": [ +
+
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+ ] +
+
+} +
+
+ +
+

Concise Representation

+

The concise representation is a terser, lossless form of the +normalized representation, where redundant Attribute type members +are omitted and the following rules are applied:

+
    +
  • +Every Property without further sub-attributes is represented +directly by the Property value only. +
    • +
  • +Every Property that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every GeoProperty without further sub-attributes is represented +by the GeoProperty's GeoJSON representation only. +
    • +
  • +Every GeoProperty that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every LanguageProperty is represented by a languageMap +key-value pair. +
    • +
  • +Every ListProperty is represented directly by the array of +Property values. +
    • +
  • +Every JsonProperty is represented by a json the value of +which is raw JSON which is not available for JSON-LD representation. +
    • +
  • +Every VocabProperty is represented by a vocab the value of +which is a compacted URI. +
    • +
  • +Every Relationship is represented by an object key-value pair. +
    • +
  • +Every ListRelationship is represented by an array of URIs. +
    • +
+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "street": { +
+
+        "languageMap": { +
+
+            "fr": "Grand Place", +
+
+            "nl": "Grote Markt" +
+
+        }  +
+
+    }, +
+
+    "isParked": { +
+
+        "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ] +
+
+
+ }, +
+
+
+"@context": [ +
+
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+
+ +
+
+ +
+
+ +
+

Concise Representation when inline Linked Entity retrieval is +used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned in an expanded format. The concise Linked Entity data corresponding to the +Relationship's target object URI is returned within an +entity sub-Attribute. Attributes of type "ListRelationship” are returned +within an entityList sub-Attribute which in turn holds an ordered +array of the Linked Entities in the +concise format corresponding to each of the targetobjectList +URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "street": { +
+
+        "languageMap": { +
+
+            "fr": "Grand Place", +
+
+            "nl": "Grote Markt" +
+
+        }  +
+
+    }, +
+
+    "isParked": { +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+        "entity": { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": "Top Parking", +
+
+ "operatedBy": { +
+
+ "object": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+     } +
+
+  }, +
+
+        "observedAt": "2017-07-29T12:00:04Z", +
+
+        "providedBy": { +
+
+            "object": "urn:ngsi-ld:Person:Bob" +
+
+        }  +
+
+    }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+ "entity": [ +
+
+   { +
+
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": "Alice" +
+
+    }, +
+
+    { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": "Bob" +
+
+    } +
+
+
+ ] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ], +
+
+ "entityList": [ +
+
+ { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+

"name": " Antwerp"

+
+
+ }, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+

"name": "Rotterdam

+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+

"name": "Amsterdam"

+
+ } +
+
+
+ ] +
+
+}, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+} +
+

Concise Representation when flattened Linked Entity retrieval +is used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of concise Entities is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional concise Linked Entity holding data corresponding to +the Relationship's target object URI is appended to the +response. For Attributes of type "ListRelationship”, an array of concise Linked Entities is appended to the response +which hold the data corresponding to each of the target URIs found +within its objectList.

+

[

+
+ { +
+
+     "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+     "type": "Vehicle", +
+
+     "brandName": "Mercedes", +
+
+     "street": { +
+
+         "languageMap": { +
+
+             "fr": "Grand Place", +
+
+             "nl": "Grote Markt" +
+
+         }  +
+
+     }, +
+
+        "isParked": {  +
+
+ "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "objectType": "OffStreetParking", +
+
+         "observedAt": "2017-07-29T12:00:04Z", +
+
+         "providedBy": { +
+
+             "object": "urn:ngsi-ld:Person:Bob" +
+
+         }  +
+
+     }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+ "tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+ }, +
+
+ "passengers": { +
+
+ "objectType": "Person", +
+
+ "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+ }, +
+
+ "route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+   ] +
+
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": "OffStreetParking", +
+
+ "name": "Top Parking", +
+
+ "operatedBy": { +
+
+ "object" "urn:ngsi-ld:Company:BigParkingCorp", +
+
+ }, +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person", +
+
+ "name": "Alice", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": " urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person", +
+
+ "name": "Bob", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": " Antwerp", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": "Rotterdam", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": "Amsterdam", +
+
+
+    "@context": [ +
+
+        "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+    ] +
+
+
+ } +
+
+] +
+
+ +
+
+ +
+

Concise representation when Language Filter is +used

+

The rules apply as defined in the previous examples. For example if +the language filter lang=fr is +specified.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "brandName": "Mercedes" +
+
+ }, +
+
+ "street": { +
+
+ "value": "Grand Place", +
+
+ "lang": "fr" +
+
+ }, +
+
+  "isParked": { +
+
+ "objectType": "OffStreetParking", +
+
+    "object": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "observedAt": "2017-07-29T12:00:04Z", +
+
+    "providedBy": { +
+
+         "object": "urn:ngsi-ld:Person:Bob" +
+
+      }  +
+
+  }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+ "tyreTreadDepths": { +
+
+ "valueList": [300, 300, 120, 6], +
+
+ "unitCode": "MMT" +
+
+}, +
+
+"passengers": { +
+
+ "objectType": "Person", +
+
+   "objectList": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] +
+
+}, +
+
+"route": { +
+
+ "objectType": "City", +
+
+ "objectList": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+   ] +
+
+}, +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"  +
+
+ ] +
+
+} +
+
+ +
+

Simplified Representation

+

The simplified representation is a collapsed, lossy representation of +an Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ } +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+"route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+], +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+
+ +
+

Simplified Representation when inline Linked Entity retrieval +is used

+

When inline Linked Entity +retrieval (see clause +4.5.23.2) is specified, any Relationships which target +Entities stored locally or include an objectType Attribute are +returned as a JSON object holding key-value pairs corresponding to the +data from the Relationship's target object URI in +simplified format. Attributes of type "ListRelationship” +are returned as array of JSON objects each holding key-value +pairs corresponding to the data obtained from the target +objectList URIs.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ }, +
+
+   "isParked": { +
+
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": " OffStreetParking",   +
+
+
+ "name": "Top Parking", +
+
+ "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+ }, +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": [ +
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person",  +
+
+ "name": "Alice" +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person",  +
+
+ "name": "Bob" +
+
+ } +
+
+], +
+
+
+    "route": [ +
+
+
+   { +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+
+ "name": " Antwerp" +
+
+     }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+
+ "name": "Rotterdam +
+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+
+ "name": "Amsterdam" +
+
+     } +
+
+    ], +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+
+ +
+

Simplified Representation when flattened Linked Entity retrieval is +used

+

When flattened Linked Entity +retrieval (see clause +4.5.23.3) is specified, an array of JSON Objects is returned. +Whenever a Relationship Attribute targets an Entity stored +locally or includes an objectType, an additional JSON Object of +key-value pairs holding data corresponding to the Relationship's +target object URI is appended to the response. For Attributes of +type "ListRelationship”, an array of JSON Objects each holding +key-value pairs corresponding to the data obtained from the target +objectList URIs is appended to the response.

+

[

+
+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": { +
+
+ "languageMap": { +
+
+ "fr": "Grand Place", +
+
+ "nl": "Grote Markt"  +
+
+ } +
+
+ } +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+ "route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+ ], +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+}, +
+
+{ +
+
+ "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "type": " OffStreetParking",   +
+
+
+ "name": "Top Parking", +
+
+ "operatedBy": "urn:ngsi-ld:Company:BigParkingCorp" +
+
+
+}, +
+
+{ +
+
+ "id": "urn:ngsi-ld:Person:Alice", +
+
+ "type": "Person",  +
+
+ "name": "Alice" +
+
+} +
+
+{ +
+
+ "id": "urn:ngsi-ld:Person:Bob", +
+
+ "type": "Person",  +
+
+ "name": "Bob" +
+
+}, +
+
+{ +
+
+
+ "id": "urn:ngsi-ld:City:Antwerp", +
+
+ "type": "City", +
+

"name": " Antwerp"

+
+
+}, +
+
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Rotterdam", +
+
+ "type": "City", +
+

"name": "Rotterdam

+
+ }, +
+
+ { +
+
+ "id": "urn:ngsi-ld:City:Amsterdam", +
+
+ "type": "City", +
+

"name": "Amsterdam"

+
+} +
+
+] +
+
+ +
+
+ +
+

Simplified Representation of Natural Language +Attributes

+

The simplified natural language representation is a collapsed +representation of an Entity, which focuses on Property Values and +Relationship objects present at the first level of the graph, and where +languageMaps are reduced to simple string properties. For example +if the language filter lang=fr is +specified.

+
+{ +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+   "brandName": "Mercedes", +
+
+ "street": "Grand Place", +
+
+   "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+ "category": { +
+
+ "vocab": "non-commercial" +
+
+ }, +
+
+
+"tyreTreadDepths": [300, 300, 120, 6], +
+
+"passengers": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"], +
+
+"route": [ +
+
+   "urn:ngsi-ld:City:Antwerp", +
+
+ "urn:ngsi-ld:City:Rotterdam", +
+
+   "urn:ngsi-ld:City:Amsterdam" +
+
+], +
+
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Multiple attribute example

+

Below is an example, where the speed of the car is provided by two +different sources. As both may be relevant at the same time, there are +two individual attribute instances for speed; each is identified by a +datasetId and both instances are represented in an array. The +datasetId enables individually creating, updating and deleting a +particular instance without affecting the instance from another +source.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "speed": [{ +
+
+    "type": "Property", +
+
+ "value": 55, +
+
+ "source": { +
+
+     "type": "Property", +
+
+ "value": "Speedometer" +
+
+ }, +
+
+ "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" +
+
+ }, +
+
+ { +
+
+    "type": "Property", +
+
+ "value": 54.5, +
+
+ "source": { +
+
+     "type": "Property", +
+
+ "value": "GPS" +
+
+ }, +
+
+ "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" +
+
+ }], +
+
+ "@context": [ +
+
+      { +
+
+ "Vehicle": "http://example.org/Vehicle", +
+
+ "speed": "http://example.org/speed", +
+
+      "source": "http://example.org/hasSource" +
+
+     }, +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

Simplified Representation of a multi-attribute

+

The simplified representation is a collapsed, lossy representation of +an Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+   "type": "Vehicle", +
+
+  "speed": { +
+
+ "dataset": { +
+
+ "urn:ngsi-ld:Property:speedometerA4567-speed": 55, +
+
+ "urn:ngsi-ld:Property:gpsBxyz123-speed": 54.5 +
+
+ } +
+
+ }, +
+
+ "@context": [ +
+
+      { +
+
+ "Vehicle": "http://example.org/Vehicle", +
+
+ "speed": "http://example.org/speed" +
+
+     }, +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

C.2.3 Parking +Entity

+

Normalized Representation

+

The normalized representation is a lossless representation of an +Entity, where every Property is defined by a type and a +value and every Relationship is defined by a type +and an object.

+

Below there is a representation of an Entity of Type "OffStreetParking". It can be observed that the +@context is composed of two different elements, the Core one and +the vocabulary-specific one.

+
+{ +
+
+   "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+   "type": "OffStreetParking", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Downtown One" +
+
+ }, +
+
+   "availableSpotNumber": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z", +
+
+     "reliability": { +
+
+       "type": "Property", +
+
+       "value": 0.7 +
+
+     }, +
+
+     "providedBy": { +
+
+        "type": "Relationship", +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+     } +
+
+ }, +
+
+ "totalSpotNumber": { +
+
+     "type": "Property", +
+
+     "value": 200 +
+
+ }, +
+
+ "location": { +
+
+ "type": "GeoProperty", +
+
+ "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.5, 41.2] +
+
+ } +
+
+ }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Concise Representation

+

The concise representation is a terser, lossless form of the +normalized representation, where redundant Attribute type members +are omitted and the following rules are applied:

+
    +
  • +Every Property without further sub-attributes is represented by +the Property value only. +
    • +
  • +Every Property that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every GeoProperty without further sub-attributes is represented +by the GeoProperty's GeoJSON representation only. +
    • +
  • +Every GeoProperty that includes further sub-attributes is +represented by a value key-value pair. +
    • +
  • +Every LanguageProperty is defined by a languageMap +key-value pair. +
    • +
  • +Every VocabProperty is represented by a vocab the value of +which is a compacted URI. +
    • +
  • +Every Relationship is defined by an object key-value pair. +
    • +
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffStreetParking", +
+
+  "name": "Downtown One", +
+
+  "availableSpotNumber": { +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z", +
+
+    "reliability": 0.7, +
+
+    "providedBy": { +
+
+      "object": "urn:ngsi-ld:Camera:C1" +
+
+    } +
+
+  }, +
+
+  "totalSpotNumber": 200, +
+
+  "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [ +
+
+      -8.5, +
+
+      41.2 +
+
+    ] +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Simplified representation

+

The Simplified Representation (also known as "keyValues") is a lossy, collapsed representation of an +Entity, which focuses on Property Values and Relationship objects +present at the first level of the graph only.

+
+{ +
+
+    "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+    "type": "OffStreetParking", +
+
+ "name": "Downtown One", +
+
+    "availableSpotNumber": 121, +
+
+ "totalSpotNumber": 200, +
+
+ "location": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.5, 41.2] +
+
+ }, +
+
+ "@context": [ +
+
+     "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

Normalized GeoJSON Representation

+

The normalized GeoJSON representation of a single Entity is defined +as a single GeoJSON Feature object as follows:

+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": { +
+
+      "type": "Property", +
+
+      "value": "Downtown One" +
+
+    }, +
+
+    "availableSpotNumber": { +
+
+      "type": "Property", +
+
+      "value": 121, +
+
+      "observedAt": "2017-07-29T12:05:02Z", +
+
+      "reliability": { +
+
+        "type": "Property", +
+
+        "value": 0.7 +
+
+      }, +
+
+      "providedBy": { +
+
+        "type": "Relationship", +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+      } +
+
+    }, +
+
+ "location": { +
+
+ "type": "GeoProperty", +
+
+ "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+ } +
+
+ }, +
+
+    "totalSpotNumber": { +
+
+      "type": "Property", +
+
+      "value": 200 +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+} +
+
+ +
+

The GeoJSON representation of multiple Entities is defined as a +GeoJSON FeatureCollection object containing an array of GeoJSON +features corresponding to the individual Entity representations.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.5, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": { +
+
+          "type": "Property", +
+
+          "value": "Downtown One" +
+
+        }, +
+
+        "availableSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 121, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+          }, +
+
+          "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 200 +
+
+        }, +
+
+ "location": { +
+
+   "type": "GeoProperty", +
+
+   "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+   } +
+
+ } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.51, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": { +
+
+          "type": "Property", +
+
+          "value": "Downtown Two" +
+
+        }, +
+
+        "availableSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 99, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.8 +
+
+          }, +
+
+          "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C2" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": { +
+
+          "type": "Property", +
+
+          "value": 100 +
+
+        }, +
+
+ "location": { +
+
+   "type": "GeoProperty", +
+
+   "value": { +
+
+ "type": "Point", +
+
+ "coordinates": [-8.51, 41.1] +
+
+   } +
+
+ } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Concise GeoJSON Representation

+

The concise GeoJSON representation of a single Entity is defined as a +single GeoJSON Feature object as follows:

+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [ +
+
+      -8.51, +
+
+      41.1 +
+
+    ] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": "Downtown One", +
+
+    "availableSpotNumber": { +
+
+      "value": 121, +
+
+      "observedAt": "2017-07-29T12:05:02Z", +
+
+      "reliability": 0.7, +
+
+      "providedBy": { +
+
+        "object": "urn:ngsi-ld:Camera:C1" +
+
+      } +
+
+    }, +
+
+    "location": { +
+
+      "type": "Point", +
+
+      "coordinates": [ +
+
+        -8.51, +
+
+        41.1 +
+
+      ] +
+
+    }, +
+
+    "totalSpotNumber": 200, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+} +
+
+ +
+

The concise GeoJSON representation of multiple Entities is defined as +a GeoJSON FeatureCollection object containing an array of GeoJSON +features corresponding to the individual Entity representations in +concise GeoJSON format.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [ +
+
+          -8.5, +
+
+          41.1 +
+
+        ] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown One", +
+
+        "availableSpotNumber": { +
+
+          "value": 121, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": 0.7, +
+
+          "providedBy": { +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": 200, +
+
+        "location": { +
+
+          "type": "Point", +
+
+          "coordinates": [ +
+
+            -8.51, +
+
+            41.1 +
+
+          ] +
+
+        } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [ +
+
+          -8.51, +
+
+          41.1 +
+
+        ] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown Two", +
+
+        "availableSpotNumber": { +
+
+          "value": 99, +
+
+          "observedAt": "2017-07-29T12:05:02Z", +
+
+          "reliability": 0.8, +
+
+          "providedBy": { +
+
+            "object": "urn:ngsi-ld:Camera:C2" +
+
+          } +
+
+        }, +
+
+        "totalSpotNumber": 100, +
+
+        "location": { +
+
+          "type": "Point", +
+
+          "coordinates": [ +
+
+            -8.51, +
+
+            41.1 +
+
+          ] +
+
+        } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

Simplified GeoJSON Representation

+

The simplified GeoJSON representation of a single Entity is defined +as a single GeoJSON Feature object where the properties represent +a collapsed representation of the Entity, which focuses on Property +Values and Relationship objects present at the first level of the +graph.

+
+{ +
+
+  "id": "urn:ngsi-ld:offstreetparking:Downtown1", +
+
+  "type": "Feature", +
+
+  "geometry": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+  }, +
+
+  "properties": { +
+
+    "type": "OffStreetParking", +
+
+    "name": "Downtown One", +
+
+    "availableSpotNumber": 121, +
+
+    "totalSpotNumber": 200, +
+
+    "location": { +
+
+   "type": "Point", +
+
+   "coordinates": [-8.51, 41.1] +
+
+ } +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

The simplified GeoJSON representation of multiple Entities is defined +as a GeoJSON FeatureCollection object containing an array of +GeoJSON features corresponding to the individual Entity representations +in simplified GeoJSON format.

+
+{ +
+
+  "type": "FeatureCollection", +
+
+  "features": [ +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.5, 41.2] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown One", +
+
+        "availableSpotNumber": 121, +
+
+        "totalSpotNumber": 200, +
+
+        "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.5, 41.2] +
+
+     } +
+
+      } +
+
+    }, +
+
+    { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown2", +
+
+      "type": "Feature", +
+
+      "geometry": { +
+
+        "type": "Point", +
+
+        "coordinates": [-8.51, 41.1] +
+
+      }, +
+
+      "properties": { +
+
+        "type": "OffStreetParking", +
+
+        "name": "Downtown Two", +
+
+        "availableSpotNumber": 99, +
+
+        "totalSpotNumber": 100, +
+
+        "location": { +
+
+    "type": "Point", +
+
+    "coordinates": [-8.51, 41.1] +
+
+     } +
+
+      } +
+
+    } +
+
+  ], +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+}   +
+
+ +
+

C.2.4 @context

+

The disposition of the @context can be as an inline JSON +object, as a dereferenceable URI or as a (multiple) combination of both. +In the examples above the @context is provided through several +dereferenceable URIs. The resulting @context (obtained by merging +the content of the resource referenced by the referred URIs) is shown +below.

+
+NOTE 1: For brevity reasons the @context does not contain the API +terms defined by clause 5.2. +
+
+NOTE 2: Some extra terms are defined because they will be used in +examples later presented. +
+
+{ +
+
+ "id": "@id", +
+
+ "type": "@type", +
+
+ "Property": "https://uri.etsi.org/ngsi-ld/Property", +
+
+ "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship", +
+
+ "value": "https://uri.etsi.org/ngsi-ld/hasValue", +
+
+ "object": { +
+
+ "@type": "@id", +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/hasObject" +
+
+ }, +
+
+ "observedAt": { +
+
+ "@type": "https://uri.etsi.org/ngsi-ld/DateTime", +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/observedAt" +
+
+ }, +
+
+ "datasetId": { +
+
+ "@id": "https://uri.etsi.org/ngsi-ld/datasetId", +
+
+ "@type": "@id" +
+
+ }, +
+
+ "location": "https://uri.etsi.org/ngsi-ld/location", +
+
+ "GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty", +
+
+ "Vehicle": "http://example.org/vehicle/Vehicle", +
+
+ "street": "http://example.org/vehicle/street", +
+
+ "brandName": "http://example.org/vehicle/brandName", +
+
+ "category": "http://example.org/vehicle/category", +
+
+ "tyreTreadDepths": "http://example.org/vehicle/tyreTreadDepths", +
+
+ "passengers": "http://example.org/vehicle/passengers", +
+
+ "speed": "http://example.org/vehicle/speed", +
+
+ "isParked": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/isParked" +
+
+ }, +
+
+ "OffStreetParking": "http://example.org/parking/OffStreetParking", +
+
+ "availableSpotNumber": "http://example.org/parking/availableSpotNumber", +
+
+ "totalSpotNumber": "http://example.org/parking/totalSpotNumber", +
+
+ "isNextToBuilding": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/isNextToBuilding" +
+
+ }, +
+
+ "reliability": "http://example.org/common/reliability",  +
+
+ "providedBy": { +
+
+ "@type": "@id", +
+
+ "@id": "http://example.org/common/providedBy" +
+
+ }, +
+
+ "name": "http://example.org/common/name", +
+
+ "commercial": +"http://example.org/vehicle/commercial", +
+
+ "non-commercial": "http://example.org/vehicle/non-commercial" +
+
+} +
+
+ +
+

C.3 Context +Source Registration

+

Below there is an example representation of a Context Source Registration. It makes use +of the @context formerly described.

+
+{ +
+
+ "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456", +
+
+    "type": "ContextSourceRegistration", +
+
+    "information": [ +
+
+   { +
+
+ "entities": [  +
+
+ { +
+
+             "id": "urn:ngsi-ld:Vehicle:A456", +
+
+ "type": "Vehicle" +
+
+            } +
+
+ ], +
+
+ "propertyNames": ["brandName","speed"], +
+
+  "relationshipNames": ["isParked"] +
+
+   },  +
+
+   { +
+
+ "entities": [ +
+
+ { +
+
+             "idPattern": ".*downtown$", +
+
+ "type": "OffStreetParking" +
+
+            }, +
+
+ { +
+
+                "idPattern": ".*47$", +
+
+ "type": "OffStreetParking" +
+
+            } +
+
+ ], +
+
+ "propertyNames": ["availableSpotNumber","totalSpotNumber"], +
+
+ "relationshipNames": ["isNextToBuilding"] +
+
+      } +
+
+ ], +
+
+ "endpoint": "http://my.csource.org:1026", +
+
+ "location": { +
+
+ "type": "Polygon", +
+
+ "coordinates": [ +
+
+             [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], +
+
+               [100.0, 1.0], [100.0, 0.0]] ] +
+
+    }, +
+
+    "managementInterval": { +
+
+ "startAt": " 2017-11-29T14:53:15Z" +
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/commonTerms.jsonld", +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld",  +
+
+ "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+

The Registration is referring to a Temporal Context Source capable of providing +temporal information from Entities of type "Vehicle" and "OffStreetParking", meeting certain id requirements. More +concretely, it can only provide the referenced Properties and +Relationships. Temporal information is provided for the given +managementInterval, i.e. related to createdAt and +modifiedAt Temporal Properties. The managementInterval is +specified as an open interval, so only a starting point is given. In +addition, the Registration example covers a particular geographical +area.

+

C.4 Context +Subscription

+

Below there is an example of a Context Subscription. It makes use of +the @context formerly described.

+
+{ +
+
+ "id": "urn:ngsi-ld:Subscription:mySubscription", +
+
+    "type": "Subscription", +
+
+    "entities": [ +
+
+ { +
+
+ "type": "Vehicle" +
+
+    } +
+
+ ], +
+
+    "watchedAttributes": ["speed"], +
+
+    "q": "speed>50", +
+
+    "geoQ": { +
+
+ "georel": "near;maxDistance==2000", +
+
+        "geometry": "Point", +
+
+        "coordinates": [-1,100] +
+
+    }, +
+
+    "notification": { +
+
+        "attributes": ["speed"], +
+
+        "format": "keyValues", +
+
+        "endpoint": { +
+
+           "uri": "http://my.endpoint.org/notify", +
+
+           "accept": "application/json" +
+
+        } +
+
+    }, +
+
+ "@context": [ +
+
+ "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+ ] +
+
+} +
+
+ +
+

The subject of the Context Subscription is Entities of Type +Vehicle which speed is greater than 50, and located close +to a certain area defined by a reference spatial point. Every time the +speed (watched Attribute) of a concerned vehicle, changes, a new +notification (including the new speed value) will be received in the +specified endpoint.

+

C.5 HTTP REST +API Examples

+

C.5.1 Introduction

+

This clause introduces some simple usage examples of the NGSI-LD API +(HTTP REST binding). They are not intended to be exhaustive but just a +sample for helping readers to understand better the present document. +ETSI ISG CIM published a Developer's Primer with many more examples, see +ETSI GR CIM 008 [i.21].

+

C.5.2 Create Entity of Type +Vehicle

+

C.5.2.1 HTTP +Request

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/ld+json +
+
+Content-Length: 556 +
+
+<Insert Here the JSON-LD representation of a Vehicle as described by +clause +C.2.2 Vehicle Entity> +
+

C.5.2.2 HTTP +Response

+
+201 Created +
+
+Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 +
+

C.5.3 Query +Entities

+

C.5.3.1 Introduction

+
+Example: Give back all the Entities of type "Vehicle" whose brandName attribute is not "Mercedes". Only give back the brandName +attribute and provide the data in the NGSI-LD Simplified Format. +
+

C.5.3.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=simplified +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.3.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Volvo", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.4 Query Entities +(Pagination)

+

C.5.4.1 Introduction

+
+Example: Give back all the Entities of type "Vehicle". Only give back the brandName +attribute and provide the data in the NGSI-LD Simplified Format. Limit +the number of entities retrieved to 2. +
+

C.5.4.2 HTTP +Request

+
+GET /ngsi-ld/v1/entities/?type= +Vehicle&format=simplified&limit=2 +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.4.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+Link: </ngsi-ld/v1/entities/?type= +Vehicle&format=simplified&limit=2&offset=2>; +rel="next"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Volvo", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A456", +
+
+    "type": "Vehicle", +
+
+    "brandName": "Mercedes", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.5 Temporal +Query

+

C.5.5.1 Introduction

+
+Example 1: Give back the temporal evolution of the attribute speed +of Entities of type "Vehicle" whose +brandName attribute is not "Mercedes" between the 1st of August +at noon and the 1st of August at 01 PM. +
+
+Example 2: Give back the temporal evolution of the attribute speed +and brandName of Entities of type "Vehicle" whose brandName attribute is not "Mercedes" between the 1st of August +at noon and the 1st of August at 01 PM. As brandName +attribute does not have any temporal evolution, brandName +attribute is omitted in the response. +
+

C.5.5.2 HTTP +Request #1

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z +
+
+Accept: application/ld+json +
+
+Link: <http://example.org/ ngsi-ld +/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.5.3 HTTP +Response #1

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": [ +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 120, +
+
+        "observedAt": "2018-08-01T12:03:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 80, +
+
+        "observedAt": "2018-08-01T12:05:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 100, +
+
+        "observedAt": "2018-08-01T12:07:00Z" +
+
+      } +
+
+    ], +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+]  +
+
+

C.5.5.2 HTTP +Request #2

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z +
+
+Accept: application/ld+json +
+
+Link: <http://example.org/ ngsi-ld +/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.5.3 HTTP +Response #2

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": [ +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 120, +
+
+        "observedAt": "2018-08-01T12:03:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 80, +
+
+        "observedAt": "2018-08-01T12:05:00Z" +
+
+      }, +
+
+      { +
+
+        "type": "Property", +
+
+        "value": 100, +
+
+        "observedAt": "2018-08-01T12:07:00Z" +
+
+      } +
+
+    ], +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+

C.5.6 Temporal +Query (Simplified Representation)

+

C.5.6.1 Introduction

+
+Example: Give back the temporal evolution of the speed attribute +for Entities of type "Vehicle" whose +brandName attribute is not "Mercedes" between the 1st of August +at noon and the 1st of August at 01 PM. Simplified +representation is required. +
+

C.5.6.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=temporalValues +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.6.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:03:00Z" +
+
+        ], +
+
+        [ +
+
+          80, +
+
+          "2018-08-01T12:05:00Z" +
+
+        ], +
+
+        [ +
+
+          100, +
+
+          "2018-08-01T12:07:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.7 Retrieve Available +Entity Types

+

C.5.7.1 Introduction

+
+Example: Give back all entity types for which entity instances are +currently available in the NGSI-LD system. +
+

C.5.7.2 HTTP +Request

+
+GET /ngsi-ld/v1/types +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.7.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:EntityTypeList:34534657", +
+
+  "type": "EntityTypeList", +
+
+  "typeList": [ +
+
+    "Vehicle", +
+
+    "OffStreetParking", +
+
+    "http://example.org/parking/ParkingSpot" +
+
+  ] +
+
+} +
+
+ +
+
+
+NOTE: All entity types that can be found in the provided @context +are given as short names, the others as Fully Qualified Names (FQNs). +
+

C.5.8 Retrieve +Details of Available Entity Types

+

C.5.8.1 Introduction

+
+Example: Give back the details of all entity types for which entity +instances are currently available in the NGSI-LD system. +
+

C.5.8.2 HTTP +Request

+
+GET /ngsi-ld/v1/types?details=true +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.8.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "http://example.org/vehicle/Vehicle", +
+
+    "type": "EntityType", +
+
+    "typeName": "Vehicle", +
+
+    "attributeNames": [ +
+
+      "brandName", +
+
+      "isParked", +
+
+      "location", +
+
+      "speed" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/OffStreetParking", +
+
+    "type": "EntityType", +
+
+    "typeName": "OffStreetParking", +
+
+    "attributeNames": [ +
+
+      "availableSpotNumber", +
+
+      "isNextToBuilding", +
+
+      "location", +
+
+      "totalSpotNumber" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/ParkingSpot", +
+
+    "type": "EntityType", +
+
+    "typeName": "http://example.org/parking/ParkingSpot", +
+
+    "attributeNames":[ +
+
+      "location", +
+
+      "http://example.org/parking/status" +
+
+    ] +
+
+  } +
+
+]  +
+
+ +
+
+
+NOTE: The type name of all entity types and all attribute names that can +be found in the provided @context are given as short names, the +others as Fully Qualified Names (FQNs). The id is always an FQN. +
+

C.5.9 Retrieve +Available Entity Type Information

+

C.5.9.1 Introduction

+
+Example: Give back the details of entity type "Vehicle" (for which entity instances are currently +available in the NGSI-LD system). +
+

C.5.9.2 HTTP +Request

+
+GET /ngsi-ld/v1/types/Vehicle +
+
+[Alternative with FQN: GET +/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle] +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.9.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "http://example.org/vehicle/Vehicle", +
+
+  "type": "EntityTypeInfo", +
+
+  "typeName": "Vehicle", +
+
+  "entityCount": 2, +
+
+  "attributeDetails": [ +
+
+    { +
+
+      "id": "http://example.org/vehicle/brandName", +
+
+      "type": "Attribute", +
+
+      "attributeName": "brandName", +
+
+      "attributeTypes": [ +
+
+        "Property" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "http://example.org/vehicle/isParked", +
+
+      "type": "Attribute", +
+
+      "attributeName": "isParked", +
+
+      "attributeTypes": [ +
+
+        "Relationship" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "https://uri.etsi.org/ngsi-ld/location", +
+
+      "type": "Attribute", +
+
+      "attributeName": "location", +
+
+      "attributeTypes": [ +
+
+        "GeoProperty" +
+
+      ] +
+
+    }, +
+
+    { +
+
+      "id": "http://example.org/vehicle/speed", +
+
+      "type": "Attribute", +
+
+      "attributeName": "speed", +
+
+      "attributeTypes": [ +
+
+        "Property" +
+
+      ] +
+
+    } +
+
+  ] +
+
+} +
+
+ +
+
+

C.5.10 Retrieve Available +Attributes

+

C.5.10.1 Introduction

+
+Example: Give back all attribute names for which entity instances are +currently available in the NGSI-LD system that have an attribute with +the respective name. +
+

C.5.10.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.10.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:AttributeList:56534657", +
+
+  "type": "AttributeList", +
+
+  "attributeList": [ +
+
+    "brandName", +
+
+    "isParked", +
+
+    "location", +
+
+    "speed", +
+
+    "http://example.org/parking/status" +
+
+  ] +
+
+} +
+
+ +
+
+
+NOTE: The attribute names that can be found in the provided +@context are given as short names, the others as fully qualified +names (FQNs). +
+

C.5.11 Retrieve +Details of Available Attributes

+

C.5.11.1 Introduction

+
+Example: Give back the details of all attributes for which entity +instances are currently available in the NGSI-LD system to which an +attribute with the respective attribute name belongs. +
+

C.5.11.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes?details=true +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.11.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+[ +
+
+  { +
+
+    "id": "http://example.org/vehicle/brandName", +
+
+    "type": "Attribute", +
+
+    "attributeName": "brandName", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/vehicle/isParked", +
+
+    "type": "Attribute", +
+
+    "attributeName": "isParked", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "https://uri.etsi.org/ngsi-ld/location", +
+
+    "type": "Attribute", +
+
+    "attributeName": "location", +
+
+    "typeNames": [ +
+
+      "Vehicle", +
+
+      "OffStreetParking", +
+
+      "http://example.org/parking/ParkingSpot" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/vehicle/speed", +
+
+    "type": "Attribute", +
+
+    "attributeName": "speed", +
+
+    "typeNames": [ +
+
+      "Vehicle" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "http://example.org/parking/status", +
+
+    "type": "Attribute", +
+
+    "attributeName": "http://example.org/parking/status", +
+
+    "typeNames": [ +
+
+      "http://example.org/parking/ParkingSpot" +
+
+    ] +
+
+  } +
+
+]  +
+
+ +
+
+
+NOTE: The attribute name and all type names that can be found in the +provided @context are given as short names, the others as Fully +Qualified Names (FQNs). The id is always an FQN. +
+

C.5.12 Retrieve +Available Attribute Information

+

C.5.12.1 Introduction

+
+Example: Give back the details of the attribute named "brandName" (for +which entity instances with an attribute of this name are currently +available in the NGSI-LD system). +
+

C.5.12.2 HTTP +Request

+
+GET /ngsi-ld/v1/attributes/brandName +
+
+[Alternative with FQN: GET +/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName] +
+
+Accept: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.12.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "http://example.org/vehicle/brandName", +
+
+  "type": "Attribute", +
+
+  "attributeName": "brandName", +
+
+  "attributeTypes": ["Property"], +
+
+  "typeNames": ["Vehicle"], +
+
+  "attributeCount": 2 +
+
+} +
+
+ +
+
+

C.5.13 Query +Entities (Natural Language Filtering)

+

C.5.13.1 Introduction

+
+Example: Give back all the Entities of type "Vehicle" where the marque attribute in British +English is "Vauxhall Viva". Only give +back the marque attribute and provide the data in the NGSI-LD +Simplified Format and only return language strings in German. +
+

C.5.13.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]== +"Vauxhall Viva"&format =simplified&lang=de +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.13.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A4567", +
+
+    "type": "Vehicle", +
+
+    "marque": "Opel Karl", +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.14 Temporal +Query (Aggregated Representation)

+

C.5.14.1 Introduction

+
+Example: Give back the maximum and average speed of Entities of type +"Vehicle" whose +brandName attribute is not "Mercedes" between the 1st of August +at noon and the 1st of August at 01 PM, aggregated by periods +of 4 minutes. +
+

C.5.14.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=aggregatedValues +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.14.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "max": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:00:00Z", +
+
+          "2018-08-01T12:04:00Z" +
+
+        ], +
+
+        [ +
+
+          100, +
+
+          "2018-08-01T12:04:00Z", +
+
+          "2018-08-01T12:08:00Z" +
+
+        ] +
+
+      ], +
+
+      "avg": [ +
+
+        [ +
+
+          120, +
+
+          "2018-08-01T12:00:00Z", +
+
+          "2018-08-01T12:04:00Z" +
+
+        ], +
+
+        [ +
+
+          90, +
+
+          "2018-08-01T12:04:00Z", +
+
+          "2018-08-01T12:08:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

C.5.15 Scope +Queries

+

C.5.15.1 Introduction

+
+Example: Give back all the Entities of type "OffStreetParking" that are within the Scope /Madrid/Centro or /Madrid/Cortes. +
+

C.5.15.2 HTTP +Request

+
+GET +/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes" +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.15.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+   { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+      "type": "OffStreetParking", +
+
+      "scope": "/Madrid/Centro", +
+
+      "name": { +
+
+         "type": "Property", +
+
+         "value": "Downtown One" +
+
+      }, +
+
+      "availableSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 121, +
+
+         "observedAt": "2017-07-29T12:05:02Z", +
+
+         "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+         }, +
+
+         "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+         } +
+
+      }, +
+
+      "totalSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 200 +
+
+      }, +
+
+      "location": { +
+
+         "type": "GeoProperty", +
+
+         "value": { +
+
+            "type": "Point", +
+
+            "coordinates": [ +
+
+               -8.5, +
+
+               41.2 +
+
+            ] +
+
+         } +
+
+      }, +
+
+      "@context": [ +
+
+         "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+      ] +
+
+   }, +
+
+   { +
+
+      "id": "urn:ngsi-ld:OffStreetParking:Corte4", +
+
+      "type": "OffStreetParking", +
+
+      "scope": [ +
+
+            "/Madrid/Cortes", +
+
+            "/Company894/UnitC" +
+
+      ], +
+
+      "name": { +
+
+         "type": "Property", +
+
+         "value": "Corte4" +
+
+      }, +
+
+      "availableSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 121, +
+
+         "observedAt": "2017-07-29T12:05:02Z", +
+
+         "reliability": { +
+
+            "type": "Property", +
+
+            "value": 0.7 +
+
+         }, +
+
+         "providedBy": { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Camera:C1" +
+
+         } +
+
+      }, +
+
+      "totalSpotNumber": { +
+
+         "type": "Property", +
+
+         "value": 100 +
+
+      }, +
+
+      "location": { +
+
+         "type": "GeoProperty", +
+
+         "value": { +
+
+            "type": "Point", +
+
+            "coordinates": [ +
+
+               -8.6, +
+
+               41.3 +
+
+            ] +
+
+         } +
+
+      }, +
+
+      "@context": [ +
+
+         "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+         "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+      ] +
+
+   } +
+
+] +
+
+ +
+
+

C.5.16 Temporal Scope Queries

+

C.5.16.1 Introduction

+
+Example: Give back the speed of all the Entities of type "Vehicle" that have been within the Scope /Madrid/Centro between the 1st of +August 2018 at noon and the 1st of August 2018 at 01 PM. Note +that the value of the Scope has to match for the given timeframe, which +means it is possible that it has been set before, e.g. on 1st +of August 2018 at 11 AM. +
+

C.5.16.2 HTTP +Request

+
+GET +/ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro" +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+

C.5.16.3 HTTP +Response

+
+200 OK +
+
+Content-Type: application/ld+json +
+
+
+[ +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+    "type": "Vehicle", +
+
+    "scope": { +
+
+  "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          "/Madrid/Centro", +
+
+          "2018-08-01T11:00:00Z" +
+
+        ] +
+
+  ] +
+
+    }, +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          30, +
+
+          "2018-08-01T12:03:00Z" +
+
+        ], +
+
+        [ +
+
+          60, +
+
+          "2018-08-01T12:05:00Z" +
+
+        ], +
+
+        [ +
+
+          50, +
+
+          "2018-08-01T12:07:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:Vehicle:A8311", +
+
+    "type": "Vehicle", +
+
+    "scope": { +
+
+  "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          [ +
+
+             "/Madrid/Centro", +
+
+             "/Company123/UnitA" +
+
+          ], +
+
+          "2018-08-01T12:10:00Z" +
+
+        ] +
+
+  ] +
+
+    }, +
+
+    "speed": { +
+
+      "type": "Property", +
+
+      "values": [ +
+
+        [ +
+
+          40, +
+
+          "2018-08-01T12:12:00Z" +
+
+        ], +
+
+        [ +
+
+          60, +
+
+          "2018-08-01T12:14:00Z" +
+
+        ], +
+
+        [ +
+
+          50, +
+
+          "2018-08-01T12:16:00Z" +
+
+        ] +
+
+      ] +
+
+    }, +
+
+    "@context": [ +
+
+      "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+  } +
+
+] +
+
+ +
+
+

Vehicle B9211 has already been within +the Scope /Madrid/Centro before the +beginning of the request interval, whereas Vehicle A8311 only entered the Scope within the request +interval. Thus in the latter case only Property values are included that +have been observed after the Scope has become valid.

+

C.6 Date +Representation

+

In NGSI-LD, a TemporalProperty is represented only by its +value, i.e. no sub-Properties of TemporalProperty nor +sub-Relationships of TemporalProperty can be conveyed. In more +formal language, a TemporalProperty does not allow reification. +The term TemporalProperty has been reserved for non-reified +structural timestamps (observedAt, createdAt, +modifiedAt, deletedAt), which capture the temporal +evolution of Attributes. Only such structural timestamps can be used as +timeproperty in Temporal Queries as mandated by clause +4.11.

+

The following example shows how time values (Date, +Time, or DateTime) can be represented in NGSI-LD as +reified Properties. A reified Property whose value is assigned the JSON +type Date, DateTime or Time, can use the JSON-LD @value +syntax structure, as shown by the example below:

+
+{ +
+
+  "id": "urn:ngsi-ld:Vehicle:B9211", +
+
+  "type": "Vehicle", +
+
+  "testedAt": { +
+
+    "type": "Property", +
+
+    "value": { +
+
+      "@type": "DateTime", +
+
+      "@value": "2018-12-04T12:00:00Z" +
+
+    } +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/vehicle.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+ +
+

One other way to achieve the same result would be to use JSON-LD +“type coercion”. With type coercion, values with a special data type are +defined with @type in the @context. This enforces the +correct type for any occurrence. An example of such a @context +fragment is shown below:

+
+"testedAt": { +
+
+  "@type": "https://uri.etsi.org/ngsi-ld/DateTime", +
+
+  "@id": "http://example.org/test/testedAt" +
+
+} +
+
+ +
+

The above does not work, when using the @context to perform +compaction, in the normalized and compact representation of NGSI-LD, due +to reification of the Property, because in this case testedAt is +a complex JSON object, which cannot be compacted to a DateTime +type as the @context specifies. Thus, the full URI +http://example.org/test/testedAt is kept, instead of the short +name testedAt. In summary, user @contexts used for the +normalized and compact NGSI-LD representation cannot use the JSON-LD +type coercion feature.

+

However, in the simplified (keyValue) representation case, such an +@context with the specification of testedAt could be used, +as there is no reification.

+

As a side note, when using the above @value + @type +approach, since type is mapped to @type in the NGSI-LD +core @context, JSON-LD compaction will result in the following +compacted value, instead of the one shown above, because @type is +compacted to type:

+
+"value": { +
+
+  "type": "DateTime", +
+
+  "@value": "2018-12-04T12:00:00Z" +
+
+} +
+

C.7 @context utilization +clarifications

+

When expanding or compacting JSON-LD terms, the JSON-LD +@context to be used is always the one provided in the current API +request. For the benefit of users and implementers the following +examples illustrate this concept.

+

The scenario starts with the creation of an Entity using a JSON-LD +@context as follows:

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/ld+json +
+
+Content-Length: 200 +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffStreetParking", +
+
+  "name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "availableSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "totalSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 200 +
+
+  }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+
+ +
+

The content of the @context utilized for the referred Entity +creation (at http://example.org/ngsi-ld/latest/parking.jsonld) is as +follows:

+
+{ +
+
+
+"OffStreetParking": "http://example.org/parking/OffStreetParking", +
+
+"availableSpotNumber": "http://example.org/parking/availableSpotNumber", +
+
+"totalSpotNumber": "http://example.org/parking/totalSpotNumber", +
+
+"name": "http://example.org/parking/name" +
+
+
+} +
+
+ +
+

At Entity creation time the implementation will perform the expansion +of terms using the JSON-LD @context depicted above.

+

Now it is needed to retrieve our initial Entity. For retrieving such +Entity, this time, a different JSON-LD @context is going to be +utilized, as follows:

+
+{ +
+
+
+"OffP": "http://example.org/parking/OffStreetParking", +
+
+"ava": "http://example.org/parking/availableSpotNumber", +
+
+"total": "http://example.org/parking/totalSpotNumber" +
+
+
+} +
+
+ +
+

This new @context, even though it makes use of the same set of +Fully Qualified Names, is defining new short strings as terms. The +reasons for that could be multiple: to facilitate data consumption by +clients, to save some bandwidth, to enable a more (or less) +human-readable response payload body in a language different than +English, etc.

+

In this particular case, the result of the Entity retrieval will be +as depicted below. It can be observed that the terms defined by the +JSON-LD @context provided at retrieval time are +used to render the Entity content (compaction), and not +the terms that were provided at creation time (which may be no longer +known by the broker).

+

It is also interesting to note that the @context array of the +response payload body contains, indeed, our header-supplied +@context:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 +
+
+Accept: application/ld+json +
+
+Link: +<http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "OffP", +
+
+  "name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "ava": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "total": { +
+
+  "type": "Property", +
+
+    "value": 200 +
+
+ }, +
+
+  "@context": [ +
+
+    "http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld", +
+
+    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+  ] +
+
+} +
+
+
+ +
+

Another interesting case to note is the one when an @context +with no matching terms or no @context at all is supplied. See the +following example:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1 +
+
+Accept: application/ld+json +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:OffStreetParking:Downtown1", +
+
+  "type": "http://example.org/parking/OffStreetParking", +
+
+  "http://example.org/parking/name": { +
+
+    "type": "Property", +
+
+    "value": "Downtown One" +
+
+  }, +
+
+  "http://example.org/parking/availableSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 121, +
+
+    "observedAt": "2017-07-29T12:05:02Z" +
+
+  }, +
+
+  "http://example.org/parking/totalSpotNumber": { +
+
+    "type": "Property", +
+
+    "value": 200 +
+
+  }, +
+
+  "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+} +
+
+
+ +
+

In this particular case it can be observed that the user names +(Entity Type, Attributes) in the response payload body have not been +compacted, and as a result the Fully Qualified Names are included. +However, the core API terms have been compacted, as the Core +@context is always considered to be implicitly present if not +specified explicitly (and that is why it is included in the JSON-LD +response, as mandated by the specification).

+

C.8 Link header +utilization clarifications

+

The JSON-LD Specification [2] states clearly that +only one HTTP Link header with the link relationship +<http://www.w3.org/ns/json-ld#context> is required to appear. Such +statement has implications in terms of providing the JSON-LD +@context when using the NGSI-LD API. The main implication is that +if the @context is a compound one, i.e. an @context which +references multiple individual @context, served by resources +behind different URIs, then a wrapper @context +has to be created and hosted. The final aim is that only one +@context is referenced from the JSON-LD Link header. This can be +illustrated with an example:

+

Imagine that it is desired to create an Entity providing +@context terms which are defined in two different JSON-LD +@context resources:

+
    +
  • +http://example.org/vehicle/v1/vehicle-context.jsonld +
    • +
  • +https://schema.org +
    • +
+

If a developer wants to reference these two @context resources +from a Link header, a wrapper @context can be easily created as +follows:

+
+{ +
+
+   "@context": [ +
+
+       "http://example.org/vehicle/v1/vehicle-context.jsonld", +
+
+       "https://schema.org", +
+
+       "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+   ] +
+
+} +
+
+ +
+

As such wrapper @context needs to be referenced from a Link header by +using a URI, then it will have to be hosted at some place on the Web. +Usually, developers will host @context using popular and simple +solutions such as GitHub or GitLab pages. As a result, developers will +be able to use @context in queries or when using "application/json" as main content type managed +by their applications.

+

It is a good practice to include the Core +@context in the wrapper @context so it can be used, +off-the-shelf, by external JSON-LD processing tools. However, it should +be noted this is not necessary for NGSI-LD, as the Core @context +is always implicitly included.

+

Then, using such wrapper @context, (in our example hosted at +https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), +the developer will be able to issue requests like:

+
+POST /ngsi-ld/v1/entities/ +
+
+Content-Type: application/json +
+
+Content-Length: 200 +
+
+Link: +<https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+{ +
+
+   "id": "urn:ngsi-ld:Vehicle:V1", +
+
+   "type": "Vehicle", +
+
+ "builtYear": { +
+
+ "type": "Property", +
+
+     "value": "2014" +
+
+ }, +
+
+   "speed": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z" +
+
+ } +
+
+} +
+
+ +
+
+201 Created +
+
+Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 +
+
+Link: < https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld +>; rel="http://www.w3.org/ns/json-ld#context"; +type="application/ld+json" +
+
+GET /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 +
+
+Accept: application/ld+json +
+
+Link: +<https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; +rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +
+
+200 OK +
+
+Content-Type: application/ld+json +
+
+{ +
+
+   "id": "urn:ngsi-ld:Vehicle:V1", +
+
+   "type": "Vehicle", +
+
+ "builtYear": { +
+
+ "type": "Property", +
+
+     "value": "2014" +
+
+ }, +
+
+   "speed": { +
+
+     "type": "Property", +
+
+     "value": 121, +
+
+ "observedAt": "2017-07-29T12:05:02Z" +
+
+ }, +
+
+    "@context": "https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld" +
+
+} +
+
+ +
+

Observe that in this case the broker is responding with the same +wrapper @context in the Link header of the HTTP Response or +within the JSON-LD response payload body (when MIME type accepted is +"application/ld+json"). However, that +could not be always the case, as there could be situations where the +broker could need to provide a wrapper @context hosted by itself, +for instance, when there are inline @context terms or when the +Core @context has not been previously included by the wrapper +@context (not recommended) provided within developer's +requests.

+

C.9 @context processing +clarifications

+

JSON-LD Specification [2] says that "If a term is +redefined within a context, all previous rules associated with the +previous definition are removed". In addition, it is stated that +"Multiple contexts may be combined using an array, which is processed in +order".

+

In contrast to the JSON-LD Specification, the NGSI-LD specification +states that the Core @context is protected and has to remain +immutable. This essentially means that the Core @context has +final precedence and, therefore, is always to be processed as the last +one in the @context array. For clarity, data providers should +place the Core @context in the final position. From the point of +view of Data providers, care has to be taken so that there are no +unexpected or undesired term expansions. See the following example:

+
+{ +
+
+   "id": "urn:ngsi-ld:Building:B1", +
+
+   "type": "Building", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Empire State" +
+
+ }, +
+
+   "location": { +
+
+     "type": "Property", +
+
+     "value": "20 West 34th Street, New York City, NY 10001" +
+
+ }, +
+
+    "@context": [ +
+
+        "https://schema.org/version/latest/schemaorg-current-https.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+

The problem of the example above is that the term "location" is defined in both the Core @context +and the schema.org user @context and the Core @context +takes precedence for the expansion. In these situations, if one wanted +to refer to the schema.org "location", the +solution is to prefix the conflicting terms, so that there cannot be any +clashing. Therefore, if the intent is to refer to https://schema.org/location +throughout, the example above can be modified as shown below:

+
+{ +
+
+   "id": "urn:ngsi-ld:Building:B1", +
+
+   "type": "Building", +
+
+ "name": { +
+
+ "type": "Property", +
+
+     "value": "Empire State" +
+
+ }, +
+
+   "schema:location": { +
+
+     "type": "Property", +
+
+     "value": "20 West 34th Street, New York City, NY 10001" +
+
+ }, +
+
+    "@context": [ +
+
+        "https://schema.org/version/latest/schemaorg-current-https.jsonld", +
+
+        "http://example.org/ngsi-ld/latest/parking.jsonld", +
+
+        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld" +
+
+    ] +
+
+} +
+
+ +
+

Note that the Core @context should be placed in the last +position of the @context array. NGSI-LD implementations are +required to render content following this approach, which has been +undertaken in order to maximize compatibility with JSON-LD processing +tools. This example works because the "schema:" prefix has already been defined by +the schema.org @context.

+
+ + diff --git a/public/16-annex-d-informative-transformation-algorithms.html b/public/16-annex-d-informative-transformation-algorithms.html new file mode 100644 index 0000000000000000000000000000000000000000..20cf98399d2ae69d04ceecf18dee63f85f2d42ae --- /dev/null +++ b/public/16-annex-d-informative-transformation-algorithms.html @@ -0,0 +1,3087 @@ + + + + + + + Annex D (informative): Transformation +Algorithms + + + + + + + + +

Annex D +(informative):
+Transformation Algorithms

+

D.1 Introduction

+

These algorithms are informative but NGSI-LD implementations should +aim at either implementing them as they are described here or devising +similar algorithms which take exactly the same input and provides +exactly the same output (or an equivalent one as per the JSON-LD +specification [2]).

+

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

+

This algorithm takes as input an NGSI-LD graph which top level node +is a particular Entity and returns as output a JSON-LD document which +represents all the data associated to the entity. The JSON-LD document +(and its associated @context) corresponds to a representation of +the Entity in JSON-LD as per the NGSI-LD Information Model.

+
+
+NOTE: +
+
+An + +early + +implementation + +of + +this + +algorithm + +can + +be + +found + +at + +[i.5]. +
+
+

Let:

+
    +
  • +G be a graph defined as follows: +
    • +
+
    +
  • +Let N be G's top level node. +
    • +
  • +N is an Entity instance of type T or types +Ts. Type name is "AliasT" or there is an Array of Type +names ["AliasT1", …,"AliasTn"], N's identifier is I. +
    • +
  • +N has 0 or more associated Property. Each Property +(Psi) is defined as follows: +
    • +
+
    +
  • +Property type identifier is Pi. +
    • +
  • +Property name is "AliasPi". +
    • +
  • +Property Value is Vi. +
    • +
  • +Property Value's associated data type is Di. +
    • +
+
    +
  • +N is the subject of 0 or more Relationship. Each Relationship is defined +as follows: +
    • +
+
    +
  • +Relationship type identifier is Ri. +
    • +
  • +Relationship name is "AliasRi". +
    • +
  • +Relationship target object identifier is Robji. +
    • +
+
    +
  • +O be a JSON object initialized to the empty object +({}). +
    • +
  • +C be a JSON-LD @context initialized as described +by annex +B. +
    • +
+

The algorithm should run as follows, provided all the preconditions +defined above are satisfied:

+
    +
  1. +Add to C a new member <"AliasT", T> or new members <"AliasT1", +T1> … <"AliasTn", Tn>. +
    2. +
  2. +Add to O two new members: +
    3. +
+
+a) <"id", I>. +
+
+b) <"type", "AliasT"> or <"type", ["AliasT1", …,"AliasTn"]> +.">. +
+
    +
  1. +For each Property Psi (Pi, "AliasP", Vi, Di) associated to N: +
    2. +
+
+a) Run Algorithm ALG1.1 taking the following inputs: +
+
    +
  • +Ps → Psi. +
    • +
  • +O → O. +
    • +
  • +C → C. +
    • +
+
    +
  1. +For each Relationship Rs (Ri, AliasRi, Robji) associated to N: +
    2. +
+
+a) Run Algorithm ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rsi. +
    • +
  • +O → O. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O, C) and end of the algorithm. +
    2. +
+

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

+

Let Ps be the Property that has to be transformed. +It is defined by (P, "AliasP", V, D), where P denotes a +Property Type Id, "AliasP" is the Property name, +V is the Property Value and D is the +Property Value's data type.

+

Ps might be associated to extra Properties or Relationships.

+

Let O be the output JSON-LD object and C the associated JSON-LD +context:

+
    +
  1. +Execute the following steps: +
    2. +
+
+a) If no member with "AliasP" is present in O, add a new member to O with +key "AliasP" and value an object structure, let it be named +Op as defined in the following. Otherwise, add all +existing members with "AliasP" to a JSON-LD array and in addition put +the object structure Op as defined in the following: +
+
    +
  • +<"type", "Property">. +
    • +
  • +If D is not a native JSON data type add a new member to Op with name +"value" and which value has to be an object structure as follows: +
    • +
+
+1) <"@type", D>. +
+
+2) <"@value", V>. +
+
    +
  • +Else If D is a native JSON data type add a new member to Op as follows: +
    • +
+
+1) <"value", V>. +
+
+b) Add a new member to C as follows: +
+
    +
  • +<"AliasP", P>. +
    • +
+
+c) For each Property associated to Ps (Pss) recursively run the present +algorithm (ALG1.1) taking the following inputs: +
+
    +
  • +Ps → Pss. +
    • +
  • +O → Op. +
    • +
  • +C → C. +
    • +
+
+d) For each Relationship associated to Ps (Rss) run algorithm +ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rss. +
    • +
  • +O → Op. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O,C) and end of the algorithm. +
    2. +
+

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

+

Let Rs be the Relationship that has to be +transformed. It is defined by (R, "AliasR", Robj), where +R denotes a Relationship Type Id, +"AliasR" is the Relationship's name and +Robj is the identifier of the target object of the +Relationship.

+

Rs might be associated to extra Properties or Relationships.

+

Let O be the output JSON-LD object and C the current JSON-LD +context:

+
    +
  1. +Execute the following statements: +
    2. +
+
+a) If no member with "AliasR" is present in O, add a new member to O with +key "AliasR" and value an object structure, let it be named +Or, and defined as in the following. Otherwise, add all +existing members with "AliasR" to a JSON-LD array and in addition put +the object structure Or as defined in the following: +
+
    +
  • +<"object", Robj>. +
    • +
  • +<"type", "Relationship">. +
    • +
+
+b) For each Property associated to Rs (Pss) run the algorithm +ALG1.1 taking the following inputs: +
+
    +
  • +Ps → Pss. +
    • +
  • +O → Or. +
    • +
  • +C → C. +
    • +
+
+c) For each Relationship associated to Rs (Rss) recursively run the +present algorithm ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rss. +
    • +
  • +O → Or. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O,C) and end of the algorithm. +
    2. +
+ + diff --git a/public/17-annex-d-informative-transformation-algorithms.html b/public/17-annex-d-informative-transformation-algorithms.html new file mode 100644 index 0000000000000000000000000000000000000000..f5401697434d4d1a139e57c1c74a07d36014931a --- /dev/null +++ b/public/17-annex-d-informative-transformation-algorithms.html @@ -0,0 +1,2936 @@ + + + + + + + Annex D (informative): Transformation Algorithms + + + + + + + +
+

Annex D +(informative):
+Transformation Algorithms

+

D.1 Introduction

+

These algorithms are informative but NGSI-LD implementations should +aim at either implementing them as they are described here or devising +similar algorithms which take exactly the same input and provides +exactly the same output (or an equivalent one as per the JSON-LD +specification [2]).

+

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

+

This algorithm takes as input an NGSI-LD graph which top level node +is a particular Entity and returns as output a JSON-LD document which +represents all the data associated to the entity. The JSON-LD document +(and its associated @context) corresponds to a representation of +the Entity in JSON-LD as per the NGSI-LD Information Model.

+
+NOTE: An early implementation of this algorithm can be found at [i.5]. +
+

Let:

+
    +
  • +G be a graph defined as follows: +
    • +
+
    +
  • +Let N be G's top level node. +
    • +
  • +N is an Entity instance of type T or types +Ts. Type name is "AliasT" or there is an Array of Type +names ["AliasT1", …,"AliasTn"], N's identifier is I. +
    • +
  • +N has 0 or more associated Property. Each Property +(Psi) is defined as follows: +
    • +
+
    +
  • +Property type identifier is Pi. +
    • +
  • +Property name is "AliasPi". +
    • +
  • +Property Value is Vi. +
    • +
  • +Property Value's associated data type is Di. +
    • +
+
    +
  • +N is the subject of 0 or more Relationship. Each Relationship is defined +as follows: +
    • +
+
    +
  • +Relationship type identifier is Ri. +
    • +
  • +Relationship name is "AliasRi". +
    • +
  • +Relationship target object identifier is Robji. +
    • +
+
    +
  • +O be a JSON object initialized to the empty object +({}). +
    • +
  • +C be a JSON-LD @context initialized as described +by annex +B. +
    • +
+

The algorithm should run as follows, provided all the preconditions +defined above are satisfied:

+
    +
  1. +Add to C a new member <"AliasT", T> or new members <"AliasT1", +T1> … <"AliasTn", Tn>. +
    2. +
  2. +Add to O two new members: +
    3. +
+
+a) <"id", I>. +
+
+b) <"type", "AliasT"> or <"type", ["AliasT1", …,"AliasTn"]> +.">. +
+
    +
  1. +For each Property Psi (Pi, "AliasP", Vi, Di) associated to N: +
    2. +
+
+a) Run Algorithm ALG1.1 taking the following inputs: +
+
    +
  • +Ps → Psi. +
    • +
  • +O → O. +
    • +
  • +C → C. +
    • +
+
    +
  1. +For each Relationship Rs (Ri, AliasRi, Robji) associated to N: +
    2. +
+
+a) Run Algorithm ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rsi. +
    • +
  • +O → O. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O, C) and end of the algorithm. +
    2. +
+

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

+

Let Ps be the Property that has to be transformed. +It is defined by (P, "AliasP", V, D), where P denotes a +Property Type Id, "AliasP" is the Property name, +V is the Property Value and D is the +Property Value's data type.

+

Ps might be associated to extra Properties or Relationships.

+

Let O be the output JSON-LD object and C the associated JSON-LD +context:

+
    +
  1. +Execute the following steps: +
    2. +
+
+a) If no member with "AliasP" is present in O, add a new member to O with +key "AliasP" and value an object structure, let it be named +Op as defined in the following. Otherwise, add all +existing members with "AliasP" to a JSON-LD array and in addition put +the object structure Op as defined in the following: +
+
    +
  • +<"type", "Property">. +
    • +
  • +If D is not a native JSON data type add a new member to Op with name +"value" and which value has to be an object structure as follows: +
    • +
+
+1) <"@type", D>. +
+
+2) <"@value", V>. +
+
    +
  • +Else If D is a native JSON data type add a new member to Op as follows: +
    • +
+
+1) <"value", V>. +
+
+b) Add a new member to C as follows: +
+
    +
  • +<"AliasP", P>. +
    • +
+
+c) For each Property associated to Ps (Pss) recursively run the present +algorithm (ALG1.1) taking the following inputs: +
+
    +
  • +Ps → Pss. +
    • +
  • +O → Op. +
    • +
  • +C → C. +
    • +
+
+d) For each Relationship associated to Ps (Rss) run algorithm +ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rss. +
    • +
  • +O → Op. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O,C) and end of the algorithm. +
    2. +
+

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

+

Let Rs be the Relationship that has to be +transformed. It is defined by (R, "AliasR", Robj), where +R denotes a Relationship Type Id, +"AliasR" is the Relationship's name and +Robj is the identifier of the target object of the +Relationship.

+

Rs might be associated to extra Properties or Relationships.

+

Let O be the output JSON-LD object and C the current JSON-LD +context:

+
    +
  1. +Execute the following statements: +
    2. +
+
+a) If no member with "AliasR" is present in O, add a new member to O with +key "AliasR" and value an object structure, let it be named +Or, and defined as in the following. Otherwise, add all +existing members with "AliasR" to a JSON-LD array and in addition put +the object structure Or as defined in the following: +
+
    +
  • +<"object", Robj>. +
    • +
  • +<"type", "Relationship">. +
    • +
+
+b) For each Property associated to Rs (Pss) run the algorithm +ALG1.1 taking the following inputs: +
+
    +
  • +Ps → Pss. +
    • +
  • +O → Or. +
    • +
  • +C → C. +
    • +
+
+c) For each Relationship associated to Rs (Rss) recursively run the +present algorithm ALG1.2 taking the following inputs: +
+
    +
  • +Rs → Rss. +
    • +
  • +O → Or. +
    • +
  • +C → C. +
    • +
+
    +
  1. +Return (O,C) and end of the algorithm. +
    2. +
+
+ + diff --git a/public/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html b/public/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html new file mode 100644 index 0000000000000000000000000000000000000000..21eb137dd7d54954033d474783c075f455b5db3c --- /dev/null +++ b/public/17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html @@ -0,0 +1,2766 @@ + + + + + + + Annex E (informative): RDF-compatible specification of +NGSI-LD meta-model + + + + + + + + +

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

+

The content of this annex is now in ETSI GS CIM 006 [i.8].

+ + diff --git a/public/18-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html b/public/18-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html new file mode 100644 index 0000000000000000000000000000000000000000..8bdee32fefa1823ba656f99baeae77449227f755 --- /dev/null +++ b/public/18-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html @@ -0,0 +1,2640 @@ + + + + + + + Annex E (informative): RDF-compatible specification of NGSI-LD +meta-model + + + + + + + +
+

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

+

The content of this annex is now in ETSI GS CIM 006 [i.8].

+
+ + diff --git a/public/18-annex-f-informative-conventions-and-syntax-guidelines.html b/public/18-annex-f-informative-conventions-and-syntax-guidelines.html new file mode 100644 index 0000000000000000000000000000000000000000..5b198d6f2b222b81bf1b735801c2f215e1c71c09 --- /dev/null +++ b/public/18-annex-f-informative-conventions-and-syntax-guidelines.html @@ -0,0 +1,2887 @@ + + + + + + + Annex F (informative): Conventions and syntax +guidelines + + + + + + + + +

Annex F +(informative):
+Conventions and syntax guidelines

+

When new terms are defined, they are marked in bold, and terms are +capitalized thereafter.

+
+
+EXAMPLE 1: +
+
+ +NGSI-LD Linked Entity +, +Linked Entity +. +
+
+

API Parameter names are always in lowercase.

+
+
+EXAMPLE 2: +
+
+ +options +. +
+
+

Entity Types are defined using lowercase but with a starting capital +letter.

+
+
+EXAMPLE 3: +
+
+Vehicle, + +Building, + +ParkingSpace. +
+
+

JSON-LD nodes and terms are always defined using camel case notation +starting with lower case.

+
+
+EXAMPLE 4: +
+
+ +createdAt +, + +value +, + +unitCode +. +
+
+

When referring to special terms, data types or words defined +previously in the present document or by other referenced +specifications, italics format is used.

+
+
+EXAMPLE 5: +
+
+ +ListRelationship, GeoProperty, Geometry, Second, Number +. +
+
+

When referring to literal strings double quotes are used.

+
+
+EXAMPLE 6: +
+
+ +"application/json" +, + +"Subscription" +. +
+
+

When referring to the JSON-LD Context the mnemonic text string +@context is used as a placeholder.

+

All the dates and times are given in UTC format.

+
+
+EXAMPLE 7: +
+
+ +2018-02-09T11:00:00Z +. +
+
+

The measurement units used in the API are those defined by the +International System of Units.

+
+
+EXAMPLE 8: +
+
+The + +distance + +in + +geo-queries + +is + +provided + +in + +meters. +
+
+

When defining application-specific elements or API extensions the +same conventions and syntax guidelines should be followed.

+ + diff --git a/public/19-annex-f-informative-conventions-and-syntax-guidelines.html b/public/19-annex-f-informative-conventions-and-syntax-guidelines.html new file mode 100644 index 0000000000000000000000000000000000000000..1ba724fbfb9c9089a22fd3e665bc5fc61d955fb8 --- /dev/null +++ b/public/19-annex-f-informative-conventions-and-syntax-guidelines.html @@ -0,0 +1,2683 @@ + + + + + + + Annex F (informative): Conventions and syntax +guidelines + + + + + + + +
+

Annex F +(informative):
+Conventions and syntax guidelines

+

When new terms are defined, they are marked in bold, and terms are +capitalized thereafter.

+
+EXAMPLE 1: NGSI-LD Linked Entity,Linked Entity. +
+

API Parameter names are always in lowercase.

+
+EXAMPLE 2: options. +
+

Entity Types are defined using lowercase but with a starting capital +letter.

+
+EXAMPLE 3: Vehicle, Building, ParkingSpace. +
+

JSON-LD nodes and terms are always defined using camel case notation +starting with lower case.

+
+EXAMPLE 4: createdAt, value, unitCode. +
+

When referring to special terms, data types or words defined +previously in the present document or by other referenced +specifications, italics format is used.

+
+EXAMPLE +5: ListRelationship, GeoProperty, Geometry, Second, Number. +
+

When referring to literal strings double quotes are used.

+
+EXAMPLE 6: "application/json", "Subscription". +
+

When referring to the JSON-LD Context the mnemonic text string +@context is used as a placeholder.

+

All the dates and times are given in UTC format.

+
+EXAMPLE 7: 2018-02-09T11:00:00Z. +
+

The measurement units used in the API are those defined by the +International System of Units.

+
+EXAMPLE 8: The distance in geo-queries is provided in meters. +
+

When defining application-specific elements or API extensions the +same conventions and syntax guidelines should be followed.

+
+ + diff --git a/public/19-annex-g-informative-localization-and-internationalization-support.html b/public/19-annex-g-informative-localization-and-internationalization-support.html new file mode 100644 index 0000000000000000000000000000000000000000..5261cfb6481659f0a1e12a86404fb04443db1059 --- /dev/null +++ b/public/19-annex-g-informative-localization-and-internationalization-support.html @@ -0,0 +1,3147 @@ + + + + + + + Annex G (informative): Localization and +Internationalization Support + + + + + + + + +

Annex +G (informative):
+Localization and Internationalization Support

+

G.0 Foreword

+

These algorithms described below are informative, but NGSI-LD +implementations should aim at either implementing them as they are +described here or providing equivalent @context elements for +their payloads to provide interoperability with their internationalized +context entities.

+

G.1 Introduction

+

G.1.0 Foreword

+

Since Internationalization is not core to context information +management, any direct support within NGSI-LD systems is limited. Annex +G proposes a series of best practices for maintaining, querying and +displaying interoperable internationalized data.

+

The content of the @context utilized for the referred Entities +within these examples uses pre-existing URNs used for +internationalization and is as follows:

+
+{ +
+
+
+"inLanguage": "http://schema.org/inLanguage", +
+
+"sameAs": "http://schema.org/sameAs" +
+
+
+} +
+
+ +
+

G.1.1 Associating +an Entity with a Natural Language

+

Where a context Entity is associated with a single natural language, +include a well-defined Property indicating the natural language +of the content. For example an Event taking place in French may be +defined as follows:

+
+{ +
+
+    "type": "Event", +
+
+    "id": "urn:ngsi-ld:Event:bonjourLeMonde", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Bonjour le Monde"  +
+
+    }, +
+
+    "description": { +
+
+         "type": "Property", +
+
+         "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple"  +
+
+    }, +
+
+    "inLanguage": { +
+
+        "type": "Property", +
+
+        "value": "fr"    +
+
+    } +
+
+} +
+
+ +
+

G.1.2 Associating +a Property with a Natural Language

+

Where a Property of a context entity can be associated to one +more natural language, include additional metadata as a sub-Property of +that Property. For example, a Hotel with booking forms available in +English, French and German may be defined as follows:

+
+{ +
+
+    "type": "Hotel, +
+
+    "id": "urn:ngsi-ld:Hotel:XXXXX", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Grand Hotel"  +
+
+    }, +
+
+ +
+
+    "bookingUrl": { +
+
+        "type": "Property", +
+
+        "value": [ +
+
+            "http://example.com/booking-in-french/",  +
+
+            "http://example.com/booking-in-english/",  +
+
+            "http://example.com/booking-in-german/" +
+
+        ], +
+
+        "inLanguage": {  +
+
+            "type": "Property",  +
+
+            "value": ["fr", "en", "de" ] +
+
+        } +
+
+    } +
+
+} +
+
+ +
+

G.1.3 Associating as +equivalent entity

+

Where equivalent context entities in multiple natural languages +exist, they may be associated with each other through the use of a +one-to-many relationship, where each relationship holds an additional +sub-Property indicating the natural language of the equivalent +entities.

+

For example, three Events (such as a walking tour which is available +in English, French and German) may be associated to each other as +follows:

+
+{ +
+
+    "type": "Event", +
+
+    "id": "urn:ngsi-ld:Event:bonjourLeMonde", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Bonjour le Monde"  +
+
+    }, +
+
+    "sameAs": [ +
+
+        { +
+
+            "type": "Relationship", +
+
+            "datasetId" : "urn:ngsi-ld:Relationship:1", +
+
+            "object": "urn:ngsi-ld:Event:helloWorld", +
+
+            "inLanguage": { +
+
+                    "type": "Property", +
+
+                    "value": "en"    +
+
+            } +
+
+        }, +
+
+        { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Event:halloWelt", +
+
+            "inLanguage": { +
+
+                    "type": "Property", +
+
+                    "value": "de"    +
+
+            } +
+
+        } +
+
+    ] +
+
+ } +
+
+ +
+

G.2 Natural Language +Collation Support

+

G.2.0 Foreword

+

All strings within an NGSI-LD system are defined and sorted as a +sequence of Unicode characters. As such there is no simple collation +mechanism to query entities ignoring case, diacritic marks or matching +diphthong single letters such as the German "ö" to also match with "oe".

+

Many databases support a degree of natural language support, in +general collation support will always depend upon the underlying +database and as such will vary from implementation to implementation. +This therefore and cannot be standardized and exposed as part of the +context information management API. Furthermore, collation is slow and +processor intensive, and for massive systems is better achieved using a +separate index.

+

For systems that require it, this clause proposes a mechanism as an +extension to a NGSI-LD Context Broker +which can be modified and used to offer collation support to the natural +language attributes found within context entities where necessary +through creating, querying and maintaining an additional property of a +property for collated attributes.

+

G.2.1 Maintain collations as +metadata

+
    +
  • +Create a subscription on the attribute (e.g. name) +
    • +
  • +Create a simple microservice to add/upsert a name.collate +property-of-a-property using a simple function to strip all diacritic +marks - for example: +
    • +
+
+str.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLower() +
+

Other substitutions could be made where local spelling rules vary +(for example different for German ö = oe).

+

G.2.2 Route +language sensitive queries via a proxy

+

Create a simple forwarding proxy around the NGSI-LD system. For any +urls with a q param (and a collate flag) run a clean-up of +the q param and amend the query string:

+

The following request on the proxy:

+
+GET +/ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name +
+

is altered on the fly and is sent to the NGSI-LD system as shown:

+
+GET +/ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22 +
+

Once again, the substitutions to make to the query string will depend +on the rules of the natural language to be supported.

+

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

+

G.3.0 Foreword

+

Context data entities are designed to be interoperable and therefore +all dates are held as UTC dates, all currency amounts are held as JSON +numbers (with the unitCode property-of-a-property available to hold the +currency), etc. Localization should not occur within the context data +entities themselves. Offering fully localized responses is not a concern +of the NGSI-LD API.

+

If localization support is necessary, a simple proxying a conversion +mechanism could be used to amend the context data received from the +NGSI-LD system before being passed to a third party system for +display.

+

G.3.1 Localizing +Dates

+

For example, if a system needs to display DateTime data in +Islamic Date format

+

The following request on the proxy:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified +
+

is forwarded unaltered and is sent to the NGSI-LD system as +shown:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified +
+

The response from the NGSI-LD system is always in UTC format:

+
+ {"date": "2020-09-28T17:13:39+02:00"} +
+
+ +
+

And the proxy can be used to update this to the desired format:

+
+ {"date": "11 Safar, 1442 1:13:39PM"} +
+
+ +
+

Using an internationalization script such as the following:

+
+new Intl.DateTimeFormat("en-u-ca-islamic", {day: 'numeric', month: +'long',weekday: 'long',year : 'numeric'}).format(date); +
+
+ +
+

It should be noted that post-localization, the transformed date is no +longer valid NGSI-LD.

+ + diff --git a/public/2-foreword.html b/public/2-foreword.html new file mode 100644 index 0000000000000000000000000000000000000000..b87a09444cf904a4e6f10bebf8f5b940f6bb39a3 --- /dev/null +++ b/public/2-foreword.html @@ -0,0 +1,2763 @@ + + + + + + + Foreword + + + + + + + + +

Foreword

+

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

+ + diff --git a/public/2-intellectual-property-rights.html b/public/2-intellectual-property-rights.html new file mode 100644 index 0000000000000000000000000000000000000000..cffe31179311fd6f6f8fd38f8d78d802bb70c1b0 --- /dev/null +++ b/public/2-intellectual-property-rights.html @@ -0,0 +1,2671 @@ + + + + + + + Intellectual Property Rights + + + + + + + +
+

Intellectual +Property Rights

+
+Essential patents +
+

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.

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

+
+ + diff --git a/public/20-annex-g-informative-localization-and-internationalization-support.html b/public/20-annex-g-informative-localization-and-internationalization-support.html new file mode 100644 index 0000000000000000000000000000000000000000..01f2f7c8f2759bd5f02a9f4e43b96c96984f16b3 --- /dev/null +++ b/public/20-annex-g-informative-localization-and-internationalization-support.html @@ -0,0 +1,3021 @@ + + + + + + + Annex G (informative): Localization and Internationalization +Support + + + + + + + +
+

Annex +G (informative):
+Localization and Internationalization Support

+

G.0 Foreword

+

These algorithms described below are informative, but NGSI-LD +implementations should aim at either implementing them as they are +described here or providing equivalent @context elements for +their payloads to provide interoperability with their internationalized +context entities.

+

G.1 Introduction

+

G.1.0 Foreword

+

Since Internationalization is not core to context information +management, any direct support within NGSI-LD systems is limited. Annex +G proposes a series of best practices for maintaining, querying and +displaying interoperable internationalized data.

+

The content of the @context utilized for the referred Entities +within these examples uses pre-existing URNs used for +internationalization and is as follows:

+
+{ +
+
+
+"inLanguage": "http://schema.org/inLanguage", +
+
+"sameAs": "http://schema.org/sameAs" +
+
+
+} +
+
+ +
+

G.1.1 Associating +an Entity with a Natural Language

+

Where a context Entity is associated with a single natural language, +include a well-defined Property indicating the natural language +of the content. For example an Event taking place in French may be +defined as follows:

+
+{ +
+
+    "type": "Event", +
+
+    "id": "urn:ngsi-ld:Event:bonjourLeMonde", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Bonjour le Monde"  +
+
+    }, +
+
+    "description": { +
+
+         "type": "Property", +
+
+         "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple"  +
+
+    }, +
+
+    "inLanguage": { +
+
+        "type": "Property", +
+
+        "value": "fr"    +
+
+    } +
+
+} +
+
+ +
+

G.1.2 Associating +a Property with a Natural Language

+

Where a Property of a context entity can be associated to one +more natural language, include additional metadata as a sub-Property of +that Property. For example, a Hotel with booking forms available in +English, French and German may be defined as follows:

+
+{ +
+
+    "type": "Hotel, +
+
+    "id": "urn:ngsi-ld:Hotel:XXXXX", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Grand Hotel"  +
+
+    }, +
+
+ +
+
+    "bookingUrl": { +
+
+        "type": "Property", +
+
+        "value": [ +
+
+            "http://example.com/booking-in-french/",  +
+
+            "http://example.com/booking-in-english/",  +
+
+            "http://example.com/booking-in-german/" +
+
+        ], +
+
+        "inLanguage": {  +
+
+            "type": "Property",  +
+
+            "value": ["fr", "en", "de" ] +
+
+        } +
+
+    } +
+
+} +
+
+ +
+

G.1.3 Associating as +equivalent entity

+

Where equivalent context entities in multiple natural languages +exist, they may be associated with each other through the use of a +one-to-many relationship, where each relationship holds an additional +sub-Property indicating the natural language of the equivalent +entities.

+

For example, three Events (such as a walking tour which is available +in English, French and German) may be associated to each other as +follows:

+
+{ +
+
+    "type": "Event", +
+
+    "id": "urn:ngsi-ld:Event:bonjourLeMonde", +
+
+    "name": { +
+
+        "type": "Property", +
+
+        "value": "Bonjour le Monde"  +
+
+    }, +
+
+    "sameAs": [ +
+
+        { +
+
+            "type": "Relationship", +
+
+            "datasetId" : "urn:ngsi-ld:Relationship:1", +
+
+            "object": "urn:ngsi-ld:Event:helloWorld", +
+
+            "inLanguage": { +
+
+                    "type": "Property", +
+
+                    "value": "en"    +
+
+            } +
+
+        }, +
+
+        { +
+
+            "type": "Relationship", +
+
+            "object": "urn:ngsi-ld:Event:halloWelt", +
+
+            "inLanguage": { +
+
+                    "type": "Property", +
+
+                    "value": "de"    +
+
+            } +
+
+        } +
+
+    ] +
+
+ } +
+
+ +
+

G.2 Natural Language +Collation Support

+

G.2.0 Foreword

+

All strings within an NGSI-LD system are defined and sorted as a +sequence of Unicode characters. As such there is no simple collation +mechanism to query entities ignoring case, diacritic marks or matching +diphthong single letters such as the German "ö" to also match with "oe".

+

Many databases support a degree of natural language support, in +general collation support will always depend upon the underlying +database and as such will vary from implementation to implementation. +This therefore and cannot be standardized and exposed as part of the +context information management API. Furthermore, collation is slow and +processor intensive, and for massive systems is better achieved using a +separate index.

+

For systems that require it, this clause proposes a mechanism as an +extension to a NGSI-LD Context Broker +which can be modified and used to offer collation support to the natural +language attributes found within context entities where necessary +through creating, querying and maintaining an additional property of a +property for collated attributes.

+

G.2.1 Maintain collations as +metadata

+
    +
  • +Create a subscription on the attribute (e.g. name) +
    • +
  • +Create a simple microservice to add/upsert a name.collate +property-of-a-property using a simple function to strip all diacritic +marks - for example: +
    • +
+
+str.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLower() +
+

Other substitutions could be made where local spelling rules vary +(for example different for German ö = oe).

+

G.2.2 Route +language sensitive queries via a proxy

+

Create a simple forwarding proxy around the NGSI-LD system. For any +urls with a q param (and a collate flag) run a clean-up of +the q param and amend the query string:

+

The following request on the proxy:

+
+GET +/ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name +
+

is altered on the fly and is sent to the NGSI-LD system as shown:

+
+GET +/ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22 +
+

Once again, the substitutions to make to the query string will depend +on the rules of the natural language to be supported.

+

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

+

G.3.0 Foreword

+

Context data entities are designed to be interoperable and therefore +all dates are held as UTC dates, all currency amounts are held as JSON +numbers (with the unitCode property-of-a-property available to hold the +currency), etc. Localization should not occur within the context data +entities themselves. Offering fully localized responses is not a concern +of the NGSI-LD API.

+

If localization support is necessary, a simple proxying a conversion +mechanism could be used to amend the context data received from the +NGSI-LD system before being passed to a third party system for +display.

+

G.3.1 Localizing +Dates

+

For example, if a system needs to display DateTime data in +Islamic Date format

+

The following request on the proxy:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified +
+

is forwarded unaltered and is sent to the NGSI-LD system as +shown:

+
+GET +/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified +
+

The response from the NGSI-LD system is always in UTC format:

+
+ {"date": "2020-09-28T17:13:39+02:00"} +
+
+ +
+

And the proxy can be used to update this to the desired format:

+
+ {"date": "11 Safar, 1442 1:13:39PM"} +
+
+ +
+

Using an internationalization script such as the following:

+
+new Intl.DateTimeFormat("en-u-ca-islamic", {day: 'numeric', month: +'long',weekday: 'long',year : 'numeric'}).format(date); +
+
+ +
+

It should be noted that post-localization, the transformed date is no +longer valid NGSI-LD.

+
+ + diff --git a/public/20-annex-h-informative-suggested-actuation-workflows.html b/public/20-annex-h-informative-suggested-actuation-workflows.html new file mode 100644 index 0000000000000000000000000000000000000000..667273f9798d32d6799bda90136ca559ca68800b --- /dev/null +++ b/public/20-annex-h-informative-suggested-actuation-workflows.html @@ -0,0 +1,4038 @@ + + + + + + + Annex H (informative): Suggested actuation +workflows + + + + + + + + +

Annex H +(informative):
+Suggested actuation workflows

+

H.1 Actuators and +feedback to the consumer

+

Actuators are things that can change their state (light on/off) or +execute actions (move forward, detect face, etc.).

+

There is currently no explicitly and precisely specified support for +actuation in the NGSI-LD API. Thus, this clause describes some +conventions that represent a proposed best-practice about how NGSI-LD +API and data models can be used for the interaction between applications +and actuators represented by NGSI-LD Entities.

+

The conventions and approach described in this clause are not +powerful enough to implement complex actuation jobs that depend on each +other and, for instance, make actuation decisions conditional on the +outcome of other actuations, unless that behaviour is implemented in a +custom way within the application logic. The concept of a more evolved +service execution logic, being a first-class citizen of the NGSI-LD API +and able to offer more structured building blocks for actuation, is +outside the scope of this annex.

+

An NGSI-LD system that comprises an actuator and supports actuation +workflows is represented as one or more NGSI-LD Entities, plus a Context Broker, a Context Source or a Context Producer, and a Context Consumer, which collaborate.

+

The interaction between actuator and Context Consumer needs to be bidirectional. +Thus, actuators are triggered by the reception of actuation-specific +commands (e.g. "set the on state of the lamp to false", to turn the +light off) that are encoded as NGSI-LD data, following a suggested data +model. They respond with feedback, similarly encoded as NGSI-LD +data.

+

Command feedbacks may serve to control the maximum operations rate a +controlling application needs to achieve, and different levels of +feedback can be requested, by associating a specific Quality of Service +value to the command:

+
    +
  • +Some applications need high operation rate but no feedback. For this +case a QoS = 0 can be used. The typical example is to control the arms +of a robot with a joystick. +
    • +
  • +Some applications need to be sure that the actuators actually received +the command request or need to get back a payload in response to the +command. In this case a QoS = 1 can be used. The typical case is +switching on a light with confirmation, or request face-detection with +consequent notification of matching events. +
    • +
  • +Commands can either require a short or a long execution time. For +commands with long execution time, the application may require a +continuous status feedback. In this case a QoS = 2 can be used. The +typical example is that of a door opening, where feedback continuously +report the current level (10 % open, 50 % open, etc.). +
    • +
+

H.2 Architecture for actuation

+

In this architecture, the application acts as Context Consumer, and the terms are used +interchangeably.

+

Commands are sent to the Context +Broker by the Context +Consumer, using the standard NGSI-LD API and a suggested +convention for representing them. In turn, feedback about command +execution is received by the Context +Consumer, both as continuous status updates and/or a final +command result.

+

More specifically, the component that handles direct communication +with the actuator is the Context +Source or the Context +Producer: it uses an actuator-specific protocol to control the +actuator and get responses and updates from it, i.e. from the real +system. Such Context +Source/Consumer or Context +Producer/Storage acting as a proxy or intermediary to the +actuator is referred to, in the following, as Context Adapter.

+

Thus, the Context Adapter is able to use the NGSI-LD API to receive +NGSI-LD command requests from the NGSI-LD Context Broker and send back command status +and result to it, as well as using an actuator-specific protocol to +communicate with the actuator.

+

The NGSI-LD Context Broker is +responsible for handling direct communication with the Context Consumer.

+

Thus, to support actuation, there is a need to specify:

+
    +
  • +Additional NGSI-LD Properties the NGSI-LD system has to have, in order +to represent and manage command Request, Status, Result. +
    • +
  • +A communication model that allows commands to flow in forward direction +and feedback to flow in reverse. This communication model has to +comprise a mapping, to be held within the NGSI-LD system, that is able +to route the command requests to the appropriate handler within the +Context Adapter and vice-versa. +
    • +
+
+ +
+
+Figure H.2-1: Architecture for actuation +
+

H.3 Structure +of Commands and additional Properties

+

H.3.0 Introduction

+

The NGSI-LD system has, in addition to the usual NGSI-LD Properties +representing the actuator's status, a set of additional, dedicated +NGSI-LD Properties associated with:

+
    +
  • +the list of available commands, i.e. the list of commands supported by +the actuator; +
    • +
  • +command endpoints, one for each command, that are used to send and +receive command related messages and optionally hold state for the +ongoing commands. +
    • +
+

The structure of the commands needs to be specified, but not the +internal format of their payloads. By using commands with a custom +payload, one can support all kinds of operations, for example:

+
    +
  • +"set-on": "true" +
    • +
  • +"detect-face": {"face-features": "…."} +
    • +
  • +"move": "forward" +
    • +
+

The data model for command requests, status and responses has to +include metadata such as the QoS of the command, its identifier, and the +custom payload itself.

+

Both the requests/responses and the list of commands the NGSI-LD +system is able to support can be represented with additional NGSI-LD +Properties, as follows.

+

H.3.1 Property for +listing available commands

+

The additional Property dedicated to the list of available commands +is as follows:

+
+"commands": { +
+
+  "type": "Property", +
+
+  "value": ["<cmd_name1>","<cmd_name2>", …, "<cmd_nameN>"] +
+
+} +
+
+ +
+

It is a Property whose value is an array of Strings, each +string representing the unique name of a supported command.

+

H.3.2 Properties for +command endpoints

+

For each available command, a set of three endpoints is to be +additionally created within the NGSI-LD system, by means of three +dedicated Properties per command. The first endpoint will manage that +command's requests, the second endpoint will manage its status, and the +third endpoint will manage command's results.

+

This convention dictates that:

+
    +
  • +The NGSI-LD Property that manages requests has the same name as the +command, e.g. "<cmd_name1>". +
    • +
  • +The NGSI-LD Property that manages results has the same name as the +command plus the "-RESULT" suffix. +
    • +
  • +The NGSI-LD Property that manages status has the same name as the +command plus the "-STATUS" suffix. +
    • +
+

Each endpoint can receive multiple requests or responses, and it +supports queueing of messages. For example, the command +moveToLocation may receive a sequence of requests that are to be +stored in an array and orderly processed depending on the arrival +timestamps. A number of respective responses may be produced, as well. +Thus, each endpoint, represented by its dedicated NGSI-LD Property, +exploits the multi-Attribute feature (see clause +4.5.5), as follows:

+

Command Request endpoint

+
+"<cmd_name>": { +
+
+  "datasetId": a URI uniquely identifying the specific command request +
+
+               (optional, if the use case does not need command queueing), +
+
+  "type":      "Property", +
+
+  "qos":       an Integer, representing the desired QoS (optional, default=0), +
+
+  "value":     custom parameters of the command (mandatory) +
+
+} +
+
+ +
+

Command Status endpoint

+
+"<cmd_name>-STATUS": { +
+
+  "datasetId": a URI uniquely identifying the specific status feedback message +
+
+               (optional, if the use case does not need queueing them), +
+
+  "type":      "Property", +
+
+  "value":     custom status of the command (mandatory) +
+
+} +
+
+ +
+

Command Result endpoint

+
+"<cmd_name>-RESULT": { +
+
+  "datasetId": a URI uniquely identifying the specific result feedback message +
+
+               (optional, if the use case does not need queueing them), +
+
+  "type":      "Property", +
+
+  "value":     custom result of the command (mandatory) +
+
+} +
+
+ +
+

Usually, the Context Adapter (or the actuator behind it), upon +receiving a command request with a specific datasetId, will then +generate status and result with the same datasetId, so that, when +the status/result is received by the application, it can link it back to +the corresponding command that is generating the received feedback. The +value of the request, status and result is generic, and it is up to the +specific application to define useful values. As an example, the PackML +language for the control of packaging machines defines a set of possible +values for statuses during an actuation workflow.

+
+
+EXAMPLE 1: +
+
+An + +example + +follows, + +where + +the + +NGSI-LD + +system + +represents + +a + +simple + +actuator. + +The + +example + +shows + +the + +NGSI-LD + +Entity + +representing + +a + +light + +that + +can + +change + +colour + +by + +manipulation + +of + +its + +brightness, + +hue + +and + +saturation + +values; + +further, + +it + +is + +possible + +to + +turn + +the + +lamp + +on + +and + +off. + +Apart + +from + +the + +id + +and + +the + +type +, + +the + +actuator + +entity + +has + +a + +set + +of + +regular + +properties + +that + +represent + +the + +current + +status + +of + +the + +lamp. + +In + +the + +example + +these + +are + +colorRGB + +and + +is-on +. + +Then + +it + +has + +the + +conventional + +Property + +named + +commands +, + +signalling + +that + +it + +supports + +four + +commands: + +"turn-on" +, + +"set +- +saturation" +, + +"set-brightness" +, + +"set-hue" +. + +Further, + +it + +has + +four + +(times + +three) + +additional + +properties + +serving + +the + +purpose + +of + +command + +endpoints. +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  +
+
+  REGULAR PROPERTIES +
+
+  "colorRGB": {"type": "Property", "value": "0xABABAB"}, +
+
+  "is-on": {"type": "Property", "value": true}, +
+
+  +
+
+  AVAILABLE COMMANDS +
+
+  "commands": { +
+
+    "type": "Property", +
+
+    "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] +
+
+  } +
+
+  +
+
+  COMMAND ENDPOINTS +
+
+  "turn-on": {"type": "Property", "value": <custom request>} +
+
+  "turn-on-STATUS": {"type": "Property", "value": <custom status>} +
+
+  "turn-on-RESULT": {"type": "Property", "value": <custom response>} +
+
+  "set-hue": ... +
+
+  "set-hue-STATUS": ... +
+
+  "set-hue-RESULT": ... +
+
+  … +
+
+} +
+
+ +
+
+
+EXAMPLE 2: +
+
+The + +following + +example, + +shows + +an + +NGSI-LD + +Entity + +Fragment + +that + +can + +be + +used + +as + +a + +command + +request + +to + +request + +that + +the + +lamp + +be + +turned + +off. +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  "turn-on": {  +
+
+    "type": "Property", +
+
+    "qos": { +
+
+      "type": "Property", +
+
+      "value": 1 +
+
+    }, +
+
+    "value": false +
+
+  } +
+
+} +
+
+ +
+
+
+EXAMPLE 3: +
+
+In + +the + +following + +example, + +the + +value + +of + +the + +command + +request + +is + +a + +more + +complex + +JSON + +Object, + +to + +show + +that + +complex + +actions + +can + +be + +conveyed + +by + +just + +one + +request. + +Further, + +the + +request + +has + +an + +identifier + +that + +makes + +it + +possible + +to + +enqueue + +it, + +together + +with + +other + +request + +that + +may + +arrive + +to + +the + +same + +command + +endpoint + +within + +a + +timespan. +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  "set-hue": {  +
+
+    "type": "Property", +
+
+    "qos": { +
+
+      "type": "Property", +
+
+      "value": 1 +
+
+    }, +
+
+    "datasetId": "myapp:mycommand:1342", +
+
+    "value": {"red": "1 seconds", "green": "2 seconds"} +
+
+  } +
+
+} +
+
+ +
+

In summary, the suggested convention prescribes a commands +property that contains a list of commands supported by the actuator. For +each of these commands, the convention requires a command endpoint +consisting of three properties, the name of the command, e.g. "turn-on", the +status property, which is the name of the command with "-STATUS" as +suffix, and the result, which is the name of the command with "-RESULT" as +suffix. Nevertheless, it is noted that such suffixes are just a +convention to distinguish the endpoints. So far, two practical +implementations exist, see clauses H.5 +and H.6, +that adopt the general scheme of this convention, with minor deviations. +In fact, this convention is derived as a generalization that leverages +the full potential of NGSI-LD sub-Attributes and multi-Attributes.

+

H.4 Communication +model

+

H.4.1 Possible communication +models

+

This convention can be leveraged by two different communication +models:

+
    +
  • +Subscription/notification, where both the application and the Context +Adapter use NGSI-LD Subscriptions to have the command requests delivered +to the appropriate handler within the Context Adapter and vice-versa. In +this case the Context Adapter acts as a Context Source as well as a Context Consumer. +
    • +
  • +Forwarding, which uses the NGSI-LD Registry and a Context Adapter able +to federate itself with the Context +Broker holding the actuator's Entity, as a means to deliver the +commands. In this case the Context Adapter acts as a Context Storage as +well as a Context Producer. +
    • +
+

H.4.2 Subscription/notification +model

+

For the interaction to work, the Context Adapter, acting as a proxy +to the actuator, subscribes to all command properties; in example 1 of +clause +H.3.2, these are "set-brightness", +"set-saturation", "set-hue" and "turn-on". When the application, acting as the +actuation client, updates the value of a command property, the Context +Adapter will receive the notification with the new value. This will be +translated into the proprietary format and forwarded to the actuator +using the actuator-specific protocol. The application in turn can +subscribe to the command status and the result. The Context Adapter +updates the status of the actuation during the execution of the command, +which is primarily relevant in the case of longer-lasting actuations, +and finally updates the result once the actuation has been completed. If +the application has subscribed to the status and result, it will receive +the corresponding notifications. Independent of the command-related +properties, the status of the actuator, held within its regular +properties, will be updated.

+

The detailed workflow is depicted in Figure +H.4.2‑1, and can be interpreted as follows:

+
    +
  1. +Application updates turn-on command Property with "value": true +
    2. +
  2. +Context Adapter gets notification of the new value true +
    3. +
  3. +Context Adapter updates turn-on-STATUS command Property with +"value": "PENDING" +
    4. +
  4. +Application gets notification of the new value "PENDING" +
    5. +
  5. +Context Adapter updates is-on regular Property with "value": true +
    6. +
  6. +Application gets notification with value: true +
    7. +
  7. +Context Adapter updates turn-on-RESULT command Property with +"value": "OK" +
    8. +
  8. +Application gets notification with of the new value "OK" +
    9. +
+
+ +
+
+Figure H.4.2-1: Steps of the actuation workflow using +subscription/notification +
+

H.4.3 Forwarding +model

+

The forwarding model uses registrations and forwarding of requests. +Actuation of commands is provisioned via registration(s) to the NGSI-LD +Registry done by the Context Adapter that states "I am responsible for +command property <X>". When the Application changes the value of a +command property, first the NGSI-LD Context +Broker asks to the NGSI-LD Registry whether the property is +delegated to some other component. The NGSI-LD Registry knows that +property <X> of the Entity is delegated to the Context Adapter. +Hence, the request is forwarded to the Context Adapter. Similar to the +other communication model, the request will then be translated into the +proprietary format and forwarded to the actuator using the +actuator-specific protocol.

+

In this model, the NGSI-LD Entity is distributed over two different +components, because some of its properties live in the Context Brokers and other properties live +in the Context Adapter, as indicated in Figure +H.4.3‑1 with a dotted rectangle.

+

The rest of the workflow, i.e. delivery of status and result messages +to the application, is done similarly to the subscription/notification +model. The detailed workflow is depicted in Figure +H.4.3‑1, and can be interpreted as follows:

+
+1) Application updates turn-on command Property with "value": true +
+
+2a) Context Broker ask Registry where +to forward the request +
+
+2b) Context Broker forwards request to +Context Adapter +
+
+3) Context Adapter updates turn-on-STATUS command Property with +"value": "PENDING" +
+
+4) Application gets notification of the new value "PENDING" +
+
+5) Context Adapter updates is-on regular Property with "value": true +
+
+6) Application gets notification with value: true +
+
+7) Context Adapter updates turn-on-RESULT command Property with +"value": "OK" +
+
+8) Application gets notification with of the new value "OK" +
+
+ +
+
+Figure H.4.3-1: Steps of the actuation workflow using forwarding +
+

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

+

The Fed4IoT project (https://fed4iot.org) leverages the +NGSI-LD architecture and the subscription/notification workflow for +actuation, in order to implement the concept of a Cloud of Things. It +enables virtualization of existing IoT sensors/actuators through Virtual +Things and IoT Brokers. IoT application developers can simply rent the +Virtual Things and the Brokers their applications need.

+

The Fed4IoT's Cloud of Things is named VirIoT (https://github.com/fed4iot/VirIoT), +and it is based on the concept of Virtual Silos as-a-service: isolated +and secure IoT environments made of Virtual Things whose data can be +accessed through standard IoT Brokers (oneM2M, NGSI, NGSI-LD, etc.).

+

In Figure +H.5‑1 a diagram shows how VirIoT implements the concept of a +large-scale and distribute NGSI-LD system that leverages the +architecture and the workflow convention described in clause +H.4.2.

+
+ +
+
+Figure H.5-1: VirIoT implementation of the NGSI-LD system and actuation +workflow +
+

All components encapsulate requests in a neutral-format message that +leverages NGSI-LD Entities at its core. But, since VirIoT uses MQTT as +its internal data distribution system, all information and actuation +commands are encoded as NGSI-LD entities, plus an additional "meta +header" that is used by the MQTT to publish and subscribe in a broadcast +fashion to multiple vThings, because the same virtual sensor can be used +by multiple applications at the same time.

+

For the actuation workflow, the "data" part of this message contains +the command request, as specified in clause +H.3, but with an additional value key that is the "command +notification uri" (cmd-nuri), representing a +location where feedback (status, result) should be sent by the +ThingVisor. For example, the cmd-nuri contains the +"data_in" MQTT topic of the issuing vSilo, so that command feedback +(status and results) are sent to it, only, instead of being broadcasted +to all subscribing applications.

+

VirIoT is agnostic to access control issues to a virtual actuator, +since the relevant policies are implemented in the specific ThingVisor, +which can grant tokens to execute actuation-commands to a subset of +vSilos only, through preliminary exchange of specific actuation-commands +(a kind of log-in).

+

Fed4IoT has developed several different ThingVisors (Context Adapters +for different sensors and hardware): for example, lamp systems and robot +devices are virtualized through specific ThingVisors, and applications +can control the lighting system of a rented conference room or control +camera and position of a bot by adding related virtual actuators to +their vSilo.

+

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

+

The IoT Agent node library [i.22] introduces the +concept of an IoT Agent, which is a component that lets a group of +devices send their data to and be managed from a Context Broker using their own native +protocols. Thus, it corresponds to the Context Adapter, and wires up the +IoT devices so that measurements can be read and commands can be sent +using NGSI-LD requests sent to an NGSI-LD compliant context Context Broker.

+

IoT Agents already exist or are in development for many IoT +communication protocols and data models. Examples include the +following:

+
    +
  • +IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON +payload) and NGSI-LD +
    • +
  • +IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and +NGSI-LD +
    • +
  • +IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an +UltraLight2.0 payload) and NGSI-LD +
    • +
  • +IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD +
    • +
+

This implementation follows the communication model described in clause +H.4.3, as explained in Figure +H.6‑1. In this workflow:

+
    +
  • +Requests between User and Context +Broker use NGSI-LD +
    • +
  • +Requests between Context Broker and +IoT Agent use NGSI-LD +
    • +
  • +Requests between IoT Agent and IoT Device use native protocols +
    • +
  • +Requests between IoT Device and IoT Agent use native protocols +
    • +
  • +Requests between IoT Agent and Context +Broker use NGSI-LD +
    • +
+
+ +
+
+Figure H.6-1: IoT Agent node library implementation of the NGSI-LD +system and actuation workflow +
+

Provisioning of the devices will be carried out (via REST API) +through IoT Agents, as well. This provisioning implies that, on the one +hand, the corresponding entities (with their commands), that represent +the devices, are generated in the Context +Broker and, on the other hand, that the corresponding IoT Agent +is configured for communication with the corresponding device, all in +one provisioning step. Below, an example how to provision a device which +supports start and stop commands is presented.

+
+{ +
+
+    "devices": [ +
+
+        { +
+
+            "device_id":   "device001", +
+
+            "entity_name": "urn:ngsi-ld:Device:001", +
+
+            "entity_type": "Device", +
+
+            "attributes": [ +
+
+                { "object_id": "s", "name": "isOpen", "type": "boolean" } +
+
+            ], +
+
+            "commands": [ +
+
+                { "name": "start", "type": "command" }, +
+
+                { "name": "stop", "type": "command" } +
+
+            ], +
+
+            "static_attributes": [ +
+
+                { "name": +
+
+                    { "type": "Text", "value": "Device:001 provision" } +
+
+                } +
+
+            ] +
+
+        } +
+
+    ] +
+
+} +
+
+ +
+ + diff --git a/public/21-annex-h-informative-suggested-actuation-workflows.html b/public/21-annex-h-informative-suggested-actuation-workflows.html new file mode 100644 index 0000000000000000000000000000000000000000..3fab47b8e8f305b5746c004e3b989a4c7520d565 --- /dev/null +++ b/public/21-annex-h-informative-suggested-actuation-workflows.html @@ -0,0 +1,3543 @@ + + + + + + + Annex H (informative): Suggested actuation workflows + + + + + + + +
+

Annex H +(informative):
+Suggested actuation workflows

+

H.1 Actuators and +feedback to the consumer

+

Actuators are things that can change their state (light on/off) or +execute actions (move forward, detect face, etc.).

+

There is currently no explicitly and precisely specified support for +actuation in the NGSI-LD API. Thus, this clause describes some +conventions that represent a proposed best-practice about how NGSI-LD +API and data models can be used for the interaction between applications +and actuators represented by NGSI-LD Entities.

+

The conventions and approach described in this clause are not +powerful enough to implement complex actuation jobs that depend on each +other and, for instance, make actuation decisions conditional on the +outcome of other actuations, unless that behaviour is implemented in a +custom way within the application logic. The concept of a more evolved +service execution logic, being a first-class citizen of the NGSI-LD API +and able to offer more structured building blocks for actuation, is +outside the scope of this annex.

+

An NGSI-LD system that comprises an actuator and supports actuation +workflows is represented as one or more NGSI-LD Entities, plus a Context Broker, a Context Source or a Context Producer, and a Context Consumer, which collaborate.

+

The interaction between actuator and Context Consumer needs to be bidirectional. +Thus, actuators are triggered by the reception of actuation-specific +commands (e.g. "set the on state of the lamp to false", to turn the +light off) that are encoded as NGSI-LD data, following a suggested data +model. They respond with feedback, similarly encoded as NGSI-LD +data.

+

Command feedbacks may serve to control the maximum operations rate a +controlling application needs to achieve, and different levels of +feedback can be requested, by associating a specific Quality of Service +value to the command:

+
    +
  • +Some applications need high operation rate but no feedback. For this +case a QoS = 0 can be used. The typical example is to control the arms +of a robot with a joystick. +
    • +
  • +Some applications need to be sure that the actuators actually received +the command request or need to get back a payload in response to the +command. In this case a QoS = 1 can be used. The typical case is +switching on a light with confirmation, or request face-detection with +consequent notification of matching events. +
    • +
  • +Commands can either require a short or a long execution time. For +commands with long execution time, the application may require a +continuous status feedback. In this case a QoS = 2 can be used. The +typical example is that of a door opening, where feedback continuously +report the current level (10 % open, 50 % open, etc.). +
    • +
+

H.2 Architecture for actuation

+

In this architecture, the application acts as Context Consumer, and the terms are used +interchangeably.

+

Commands are sent to the Context +Broker by the Context +Consumer, using the standard NGSI-LD API and a suggested +convention for representing them. In turn, feedback about command +execution is received by the Context +Consumer, both as continuous status updates and/or a final +command result.

+

More specifically, the component that handles direct communication +with the actuator is the Context +Source or the Context +Producer: it uses an actuator-specific protocol to control the +actuator and get responses and updates from it, i.e. from the real +system. Such Context +Source/Consumer or Context +Producer/Storage acting as a proxy or intermediary to the +actuator is referred to, in the following, as Context Adapter.

+

Thus, the Context Adapter is able to use the NGSI-LD API to receive +NGSI-LD command requests from the NGSI-LD Context Broker and send back command status +and result to it, as well as using an actuator-specific protocol to +communicate with the actuator.

+

The NGSI-LD Context Broker is +responsible for handling direct communication with the Context Consumer.

+

Thus, to support actuation, there is a need to specify:

+
    +
  • +Additional NGSI-LD Properties the NGSI-LD system has to have, in order +to represent and manage command Request, Status, Result. +
    • +
  • +A communication model that allows commands to flow in forward direction +and feedback to flow in reverse. This communication model has to +comprise a mapping, to be held within the NGSI-LD system, that is able +to route the command requests to the appropriate handler within the +Context Adapter and vice-versa. +
    • +
+
+ +
+
+Figure H.2-1: Architecture for actuation +
+

H.3 Structure +of Commands and additional Properties

+

H.3.0 Introduction

+

The NGSI-LD system has, in addition to the usual NGSI-LD Properties +representing the actuator's status, a set of additional, dedicated +NGSI-LD Properties associated with:

+
    +
  • +the list of available commands, i.e. the list of commands supported by +the actuator; +
    • +
  • +command endpoints, one for each command, that are used to send and +receive command related messages and optionally hold state for the +ongoing commands. +
    • +
+

The structure of the commands needs to be specified, but not the +internal format of their payloads. By using commands with a custom +payload, one can support all kinds of operations, for example:

+
    +
  • +"set-on": "true" +
    • +
  • +"detect-face": {"face-features": "…."} +
    • +
  • +"move": "forward" +
    • +
+

The data model for command requests, status and responses has to +include metadata such as the QoS of the command, its identifier, and the +custom payload itself.

+

Both the requests/responses and the list of commands the NGSI-LD +system is able to support can be represented with additional NGSI-LD +Properties, as follows.

+

H.3.1 Property for +listing available commands

+

The additional Property dedicated to the list of available commands +is as follows:

+
+"commands": { +
+
+  "type": "Property", +
+
+  "value": ["<cmd_name1>","<cmd_name2>", …, "<cmd_nameN>"] +
+
+} +
+
+ +
+

It is a Property whose value is an array of Strings, each +string representing the unique name of a supported command.

+

H.3.2 Properties for +command endpoints

+

For each available command, a set of three endpoints is to be +additionally created within the NGSI-LD system, by means of three +dedicated Properties per command. The first endpoint will manage that +command's requests, the second endpoint will manage its status, and the +third endpoint will manage command's results.

+

This convention dictates that:

+
    +
  • +The NGSI-LD Property that manages requests has the same name as the +command, e.g. "<cmd_name1>". +
    • +
  • +The NGSI-LD Property that manages results has the same name as the +command plus the "-RESULT" suffix. +
    • +
  • +The NGSI-LD Property that manages status has the same name as the +command plus the "-STATUS" suffix. +
    • +
+

Each endpoint can receive multiple requests or responses, and it +supports queueing of messages. For example, the command +moveToLocation may receive a sequence of requests that are to be +stored in an array and orderly processed depending on the arrival +timestamps. A number of respective responses may be produced, as well. +Thus, each endpoint, represented by its dedicated NGSI-LD Property, +exploits the multi-Attribute feature (see clause +4.5.5), as follows:

+

Command Request endpoint

+
+"<cmd_name>": { +
+
+  "datasetId": a URI uniquely identifying the specific command request +
+
+               (optional, if the use case does not need command queueing), +
+
+  "type":      "Property", +
+
+  "qos":       an Integer, representing the desired QoS (optional, default=0), +
+
+  "value":     custom parameters of the command (mandatory) +
+
+} +
+
+ +
+

Command Status endpoint

+
+"<cmd_name>-STATUS": { +
+
+  "datasetId": a URI uniquely identifying the specific status feedback message +
+
+               (optional, if the use case does not need queueing them), +
+
+  "type":      "Property", +
+
+  "value":     custom status of the command (mandatory) +
+
+} +
+
+ +
+

Command Result endpoint

+
+"<cmd_name>-RESULT": { +
+
+  "datasetId": a URI uniquely identifying the specific result feedback message +
+
+               (optional, if the use case does not need queueing them), +
+
+  "type":      "Property", +
+
+  "value":     custom result of the command (mandatory) +
+
+} +
+
+ +
+

Usually, the Context Adapter (or the actuator behind it), upon +receiving a command request with a specific datasetId, will then +generate status and result with the same datasetId, so that, when +the status/result is received by the application, it can link it back to +the corresponding command that is generating the received feedback. The +value of the request, status and result is generic, and it is up to the +specific application to define useful values. As an example, the PackML +language for the control of packaging machines defines a set of possible +values for statuses during an actuation workflow.

+
+EXAMPLE 1: An example follows, where the NGSI-LD system represents a +simple actuator. The example shows the NGSI-LD Entity representing a +light that can change colour by manipulation of its brightness, hue and +saturation values; further, it is possible to turn the lamp on and off. +Apart from the id and the type, the actuator entity has a +set of regular properties that represent the current status of the lamp. +In the example these are colorRGB and is-on. Then it has +the conventional Property named commands, signalling that it +supports four commands: "turn-on", "set-saturation", "set-brightness", "set-hue". Further, it has four (times three) +additional properties serving the purpose of command endpoints. +
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  +
+
+  REGULAR PROPERTIES +
+
+  "colorRGB": {"type": "Property", "value": "0xABABAB"}, +
+
+  "is-on": {"type": "Property", "value": true}, +
+
+  +
+
+  AVAILABLE COMMANDS +
+
+  "commands": { +
+
+    "type": "Property", +
+
+    "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] +
+
+  } +
+
+  +
+
+  COMMAND ENDPOINTS +
+
+  "turn-on": {"type": "Property", "value": <custom request>} +
+
+  "turn-on-STATUS": {"type": "Property", "value": <custom status>} +
+
+  "turn-on-RESULT": {"type": "Property", "value": <custom response>} +
+
+  "set-hue": ... +
+
+  "set-hue-STATUS": ... +
+
+  "set-hue-RESULT": ... +
+
+  … +
+
+} +
+
+ +
+
+EXAMPLE 2: The following example, shows an NGSI-LD Entity Fragment that +can be used as a command request to request that the lamp be turned off. +
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  "turn-on": {  +
+
+    "type": "Property", +
+
+    "qos": { +
+
+      "type": "Property", +
+
+      "value": 1 +
+
+    }, +
+
+    "value": false +
+
+  } +
+
+} +
+
+ +
+
+EXAMPLE 3: In the following example, the value of the command request is +a more complex JSON Object, to show that complex actions can be conveyed +by just one request. Further, the request has an identifier that makes +it possible to enqueue it, together with other request that may arrive +to the same command endpoint within a timespan. +
+
+{ +
+
+  "id": "urn:ngsi-ld:pHueActuator:light1", +
+
+  "type": "Lamp", +
+
+  "set-hue": {  +
+
+    "type": "Property", +
+
+    "qos": { +
+
+      "type": "Property", +
+
+      "value": 1 +
+
+    }, +
+
+    "datasetId": "myapp:mycommand:1342", +
+
+    "value": {"red": "1 seconds", "green": "2 seconds"} +
+
+  } +
+
+} +
+
+ +
+

In summary, the suggested convention prescribes a commands +property that contains a list of commands supported by the actuator. For +each of these commands, the convention requires a command endpoint +consisting of three properties, the name of the command, e.g. "turn-on", the +status property, which is the name of the command with "-STATUS" as +suffix, and the result, which is the name of the command with "-RESULT" as +suffix. Nevertheless, it is noted that such suffixes are just a +convention to distinguish the endpoints. So far, two practical +implementations exist, see clauses H.5 +and H.6, +that adopt the general scheme of this convention, with minor deviations. +In fact, this convention is derived as a generalization that leverages +the full potential of NGSI-LD sub-Attributes and multi-Attributes.

+

H.4 Communication +model

+

H.4.1 Possible communication +models

+

This convention can be leveraged by two different communication +models:

+
    +
  • +Subscription/notification, where both the application and the Context +Adapter use NGSI-LD Subscriptions to have the command requests delivered +to the appropriate handler within the Context Adapter and vice-versa. In +this case the Context Adapter acts as a Context Source as well as a Context Consumer. +
    • +
  • +Forwarding, which uses the NGSI-LD Registry and a Context Adapter able +to federate itself with the Context +Broker holding the actuator's Entity, as a means to deliver the +commands. In this case the Context Adapter acts as a Context Storage as +well as a Context Producer. +
    • +
+

H.4.2 Subscription/notification +model

+

For the interaction to work, the Context Adapter, acting as a proxy +to the actuator, subscribes to all command properties; in EXAMPLE 1 of +clause +H.3.2, these are "set-brightness", +"set-saturation", "set-hue" and "turn-on". When the application, acting as the +actuation client, updates the value of a command property, the Context +Adapter will receive the notification with the new value. This will be +translated into the proprietary format and forwarded to the actuator +using the actuator-specific protocol. The application in turn can +subscribe to the command status and the result. The Context Adapter +updates the status of the actuation during the execution of the command, +which is primarily relevant in the case of longer-lasting actuations, +and finally updates the result once the actuation has been completed. If +the application has subscribed to the status and result, it will receive +the corresponding notifications. Independent of the command-related +properties, the status of the actuator, held within its regular +properties, will be updated.

+

The detailed workflow is depicted in Figure +H.4.2‑1, and can be interpreted as follows:

+
    +
  1. +Application updates turn-on command Property with "value": true +
    2. +
  2. +Context Adapter gets notification of the new value true +
    3. +
  3. +Context Adapter updates turn-on-STATUS command Property with +"value": "PENDING" +
    4. +
  4. +Application gets notification of the new value "PENDING" +
    5. +
  5. +Context Adapter updates is-on regular Property with "value":true +
    6. +
  6. +Application gets notification with value: true +
    7. +
  7. +Context Adapter updates turn-on-RESULT command Property with +"value": "OK" +
    8. +
  8. +Application gets notification with of the new value "OK" +
    9. +
+
+ +
+
+Figure H.4.2-1: Steps of the actuation workflow using +subscription/notification +
+

H.4.3 Forwarding +model

+

The forwarding model uses registrations and forwarding of requests. +Actuation of commands is provisioned via registration(s) to the NGSI-LD +Registry done by the Context Adapter that states "I am responsible for +command property <X>". When the Application changes the value of a +command property, first the NGSI-LD Context +Broker asks to the NGSI-LD Registry whether the property is +delegated to some other component. The NGSI-LD Registry knows that +property <X> of the Entity is delegated to the Context Adapter. +Hence, the request is forwarded to the Context Adapter. Similar to the +other communication model, the request will then be translated into the +proprietary format and forwarded to the actuator using the +actuator-specific protocol.

+

In this model, the NGSI-LD Entity is distributed over two different +components, because some of its properties live in the Context Brokers and other properties live +in the Context Adapter, as indicated in Figure +H.4.3‑1 with a dotted rectangle.

+

The rest of the workflow, i.e. delivery of status and result messages +to the application, is done similarly to the subscription/notification +model. The detailed workflow is depicted in Figure +H.4.3‑1, and can be interpreted as follows:

+
+1) Application updates turn-on command Property with "value": true +
+
+2a) Context Broker ask Registry where +to forward the request +
+
+2b) Context Broker forwards request to +Context Adapter +
+
+3) Context Adapter updates turn-on-STATUS command Property with +"value": "PENDING" +
+
+4) Application gets notification of the new value "PENDING" +
+
+5) Context Adapter updates is-on regular Property with "value":true +
+
+6) Application gets notification with value: true +
+
+7) Context Adapter updates turn-on-RESULT command Property with +"value": "OK" +
+
+8) Application gets notification with of the new value "OK" +
+
+ +
+
+Figure H.4.3-1: Steps of the actuation workflow using forwarding +
+

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

+

The Fed4IoT project (https://fed4iot.org) leverages the NGSI-LD +architecture and the subscription/notification workflow for actuation, +in order to implement the concept of a Cloud of Things. It enables +virtualization of existing IoT sensors/actuators through Virtual Things +and IoT Brokers. IoT application developers can simply rent the Virtual +Things and the Brokers their applications need.

+

The Fed4IoT's Cloud of Things is named VirIoT +(https://github.com/fed4iot/VirIoT), and it is based on the concept of +Virtual Silos as-a-service: isolated and secure IoT environments made of +Virtual Things whose data can be accessed through standard IoT Brokers +(oneM2M, NGSI, NGSI-LD, etc.).

+

In Figure +H.5‑1 a diagram shows how VirIoT implements the concept of a +large-scale and distribute NGSI-LD system that leverages the +architecture and the workflow convention described in clause +H.4.2.

+
+ +
+
+Figure H.5-1: VirIoT implementation of the NGSI-LD system and actuation +workflow +
+

All components encapsulate requests in a neutral-format message that +leverages NGSI-LD Entities at its core. But, since VirIoT uses MQTT as +its internal data distribution system, all information and actuation +commands are encoded as NGSI-LD entities, plus an additional "meta +header" that is used by the MQTT to publish and subscribe in a broadcast +fashion to multiple vThings, because the same virtual sensor can be used +by multiple applications at the same time.

+

For the actuation workflow, the "data" part of this message contains +the command request, as specified in clause +H.3, but with an additional value key that is the "command +notification uri" (cmd-nuri), representing a +location where feedback (status, result) should be sent by the +ThingVisor. For example, the cmd-nuri contains the +"data_in" MQTT topic of the issuing vSilo, so that command feedback +(status and results) are sent to it, only, instead of being broadcasted +to all subscribing applications.

+

VirIoT is agnostic to access control issues to a virtual actuator, +since the relevant policies are implemented in the specific ThingVisor, +which can grant tokens to execute actuation-commands to a subset of +vSilos only, through preliminary exchange of specific actuation-commands +(a kind of log-in).

+

Fed4IoT has developed several different ThingVisors (Context Adapters +for different sensors and hardware): for example, lamp systems and robot +devices are virtualized through specific ThingVisors, and applications +can control the lighting system of a rented conference room or control +camera and position of a bot by adding related virtual actuators to +their vSilo.

+

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

+

The IoT Agent node library [i.22] introduces the +concept of an IoT Agent, which is a component that lets a group of +devices send their data to and be managed from a Context Broker using their own native +protocols. Thus, it corresponds to the Context Adapter, and wires up the +IoT devices so that measurements can be read and commands can be sent +using NGSI-LD requests sent to an NGSI-LD compliant context Context Broker.

+

IoT Agents already exist or are in development for many IoT +communication protocols and data models. Examples include the +following:

+
    +
  • +IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON +payload) and NGSI-LD +
    • +
  • +IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and +NGSI-LD +
    • +
  • +IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an +UltraLight2.0 payload) and NGSI-LD +
    • +
  • +IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD +
    • +
+

This implementation follows the communication model described in clause +H.4.3, as explained in Figure +H.6‑1. In this workflow:

+
    +
  • +Requests between User and Context +Broker use NGSI-LD +
    • +
  • +Requests between Context Broker and +IoT Agent use NGSI-LD +
    • +
  • +Requests between IoT Agent and IoT Device use native protocols +
    • +
  • +Requests between IoT Device and IoT Agent use native protocols +
    • +
  • +Requests between IoT Agent and Context +Broker use NGSI-LD +
    • +
+
+ +
+
+Figure H.6-1: IoT Agent node library implementation of the NGSI-LD +system and actuation workflow +
+

Provisioning of the devices will be carried out (via REST API) +through IoT Agents, as well. This provisioning implies that, on the one +hand, the corresponding entities (with their commands), that represent +the devices, are generated in the Context +Broker and, on the other hand, that the corresponding IoT Agent +is configured for communication with the corresponding device, all in +one provisioning step. Below, an example how to provision a device which +supports start and stop commands is presented.

+
+{ +
+
+    "devices": [ +
+
+        { +
+
+            "device_id":   "device001", +
+
+            "entity_name": "urn:ngsi-ld:Device:001", +
+
+            "entity_type": "Device", +
+
+            "attributes": [ +
+
+                { "object_id": "s", "name": "isOpen", "type": "boolean" } +
+
+            ], +
+
+            "commands": [ +
+
+                { "name": "start", "type": "command" }, +
+
+                { "name": "stop", "type": "command" } +
+
+            ], +
+
+            "static_attributes": [ +
+
+                { "name": +
+
+                    { "type": "Text", "value": "Device:001 provision" } +
+
+                } +
+
+            ] +
+
+        } +
+
+    ] +
+
+} +
+
+ +
+
+ + diff --git a/public/21-annex-i-informative-change-history.html b/public/21-annex-i-informative-change-history.html new file mode 100644 index 0000000000000000000000000000000000000000..498adad47a4bba7bf5bd740180c26a5b6d0067c6 --- /dev/null +++ b/public/21-annex-i-informative-change-history.html @@ -0,0 +1,3880 @@ + + + + + + + Annex I (informative): Change history + + + + + + + + +

Annex I (informative):
+Change history

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Date +
+Version +
+Information about changes +
+February 2020 +
+1.2.10 +
+Early draft copied from API version 1.2.1 +
+February 2020 +
+1.2.11 +
+Unicode characters. Query Language syntax changes to Attribute path, and +extension to accept specifying just Query or Geoquery when Querying +Entities +
+
+Acknowledgements to EU projects. Lightweight Figures +
+March 2020 +
+1.2.12 +
+Extending to other interactions the above changes to query entities +interaction +
+
+Changes to ABNF Query Language syntax to access complex objects value of +properties more easily +
+
+Generalized Notification Headers, in order to carry authentication etc., +info +
+
+Novel &option=count and associated Header to indicate number of +Entities in response to a query +
+
+Novel/entityOperations/query and/temporal/entityOperations/query +endpoints to perform query via POST +
+
+Clarified attrs URL parameter behaviour +
+
+Support for Multiple Attributes +
+
+Support for Multiple Tenants +
+May 2020 +
+Candidate 1.2.13 +
+from 101r1: Multi-Attribute-Support-fix-in-4.5.5 +
+
+from 102r1: Batch_Operation_Error_Codes +
+
+from 110r1: JSON-LD Validation clause +
+
+from 112r1: IRI Support for International Characters +
+
+from 115r2: More Core Context Changes +
+
+from 130: Entity Types +
+
+MQTT Notifications +
+
+GeoJSON Representation +
+9 July 2020 +
+1.3.1 +
+Technical Officer verifications for submission to editHelp! publication +pre-processing +
+August 2020 +
+1.3.2 +
+New baseline towards v1.4.1 +
+November 2020 +
+1.3.3 +
+From 272r1: Support for natural languages via LanguageProperty; annex +G +
+December 2020 +
+1.3.4 +
+From 319: Align Table 6.8.3.2‑1 +with clause +5.10.2 for query via attrs +
+December 2020 +
+1.3.4 +
+From 310r2: Dot vs. comma in DateTime +
+December 2020 +
+1.3.4 +
+From 309r1: Remove sentences referring to old multi attributes +representation +
+December 2020 +
+1.3.4 +
+From 308r: id and type for JSON-LD compliance +
+December 2020 +
+1.3.4 +
+From 313r1: FIXES to Cross domain data model for LanguageProperties +
+
+Bug fixes and errata +
+December 2020 +
+1.3.5 +
+From 275r3: Temporal Aggregation Functions +
+December 2020 +
+1.4.0 +
+1.3.5 with small typos corrected, approved as 1.4.0 +
+January 2021 +
+1.4.1 +
+ETSI Technical Officer review for ETSI EditHelp publication +pre-processing +
+March 2021 +
+1.4.2 +
+Editorial Changes, clarifications added, better references, figures +replacements and corrections, figures merged, typos, code identation +
+April 2021 +
+1.4.2 +
+Temporal Pagination +
+April 2021 +
+1.4.2 +
+Clarified behavior when multiple instances of the same Entity are in an +input array +
+July 2021 +
+1.4.3 +
+From 130r6: NGSI-LD Scope +
+July 2021 +
+1.4.3 +
+From 143r6: Storing, managing and serving @contexts +
+July 2021 +
+1.4.3 +
+From 120r4: API structuring +
+October 2021 +
+1.4.4 +
+From 156: Remove static elements from temporal representations +
+October 2021 +
+1.4.4 +
+From 155: Existence query +
+October 2021 +
+1.4.4 +
+From 152: Remove null value deletion +
+October 2021 +
+1.4.4 +
+From 151: attrs missing in core context +
+October 2021 +
+1.5.1 +
+ETSI Technical Officer review for ETSI EditHelp publication +pre-processing +
+November 2021 +
+1.5.2 +
+First early draft after EditHelp publication of V1.5.1 to prepare next +V1.6.1 publication +
+January 2022 +
+1.5.3 +
+Concise representation +
+May 2022 +
+1.5.4 +
+PUT/PATCH Entity +
+May 2022 +
+1.5.4 +
+Distributed operations +
+July 2022 +
+1.5.5 +
+From 99r6: Deletions and advanced notifications +
+July 2022 +
+1.5.5 +
+From 106r1: Workflow for actuation +
+July 2022 +
+1.5.5 +
+From 105r1: Context Source Info in Context Source Registration +
+July 2022 +
+1.5.5 +
+From 93r1: default context clarification +
+July 2022 +
+1.5.5 +
+From 91r1: CR_on_Scope_ABNF_format +
+Juy 2022 +
+1.6.1 +
+Final Technical Official check for EditHelp publication +
+October 2022 +
+1.6.2 +
+New early draft: +
+
+corrected Annex +C6 date representation +
+
+from 149r3: generalized description of @context in bullet lists +
+
+Fixed usage of NGSI-LD Null in Attributes' definitions +
+December 2022 +
+1.6.4 +
+From 188r2_Registration_Clarifications +
+December 2022 +
+1.6.4 +
+From 182r2_Add_NGSI-LD_Roles_for_Context_Registration +
+December 2022 +
+1.6.4 +
+From 156r2 VocabProperty/URI type coercion +
+December 2022 +
+1.6.4 +
+177r2 Clarify usage of Accept, Content-Type and Linked @context when +forwarding to partial Context Brokers +
+December 2022 +
+1.6.4 +
+178 Add Batch Query to Federation Ops +
+December 2022 +
+1.6.4 +
+183r1 Clarify Temporal query behaviour +
+December 2022 +
+1.6.4 +
+149r4 Forbid scoped and nested @contexts +
+December 2022 +
+1.6.4 +
+023006 Fixing CSource registration example in C.3 +
+December 2022 +
+1.6.4 +
+Fix: Tenants URI becomes String +
+December 2022 +
+1.6.4 +
+Fix: POST-QUERY-COUNT-PAGINATION +
+December 2022 +
+1.6.4 +
+Fix: CHECK-URI-PARAM +
+December 2022 +
+1.6.4 +
+Updated examples and text to context v1.7.jsonld +
+March 2023 +
+1.6.6 +
+CIM(23)000006_Adding_previousValue_to_GeoProperty_type_definition +
+March 2023 +
+1.6.6 +
+cSource -> CSource; "implementations shall do the following" +
+March 2023 +
+1.6.7 +
+000013r4_Updated_Distributed_Execution_Behaviour +
+March 2023 +
+1.6.8 +
+CIM(22)000195r3_type_passing_for_M2M_callReviewed +
+April 2023 +
+1.6.9 +
+Fixing URI🡪String datatypes +
+June 2023 +
+1.7.2 +
+CIM(23)000053r1_Entity_Graph_Retrieval (for FIWARE SUMMIT) +
+June 2023 +
+1.7.3 +
+000056r2_APIv172_towards_v18.docx (for FIWARE SUMMIT) +
+October 2023 +
+1.7.4 +
+From 25023r2: Use Temporal Evolution instead of Temporal Representation ++ Updated figures in clause +5 and 6 +
+November 2023 +
+1.7.5 +
+From 68r5: Additional id only format and attribute projection via pick +and omit +
+
+From 121r1: Relationship as Array +
+
+From 123r1: URN Namespace Definitions +
+
+From 149r3: Allow Broader Local Requests +
+
+From 153r1: JsonProperty +
+
+From 159: Bug fixed in CIM 009: GeoJSON responses in figures +
+
+From 160: Replace Attribute fix +
+December 2023 +
+1.7.6 +
+From 164: Host alias /info Endpoint +
+
+From 154r2: EntityMap +
+
+Updated figure in clause +6.2 +
+January 2024 +
+1.7.7 +
+From 168r1: 504 error instead of 503 in JSON-LD context endpoints +
+
+From 169r1: Allow forbidden characters +
+
+From 170: Remove Scope from PATCH /attrs operations +
+
+From 1005r2: URI for value of several attributes +
+
+From 173r2: Clarify match in distributed operations +
+
+From 174: Protect core context +
+
+From 25002r2: API Issue #10 Filter on value with specific datasetId +
+January 2024 +
+1.7.8 +
+From 164r5: fix Tenant in Host Alias (164) and /info/sourceIdentity +Endpoint + figure +
+
+Updated figure in clause +6.2 +
+
+Updated figures in clause +4.2 +
+January 2024 +
+1.7.9 +
+CIM(24)000007r2_Query_Language_Extension_for_Linked_Entity_Retrieval +
+January 2024 +
+1.7.10 +
+Internal revision, cleanup +
+January 2024 +
+1.7.10 +
+FIX: CIM(24)000015_Projection_attributes_error_messaging +
+January 2024 +
+1.7.10 +
+FIX: CIM(24)000014r1_POST_Query_Parameters +
+January 2024 +
+1.7.11 +
+TO revision +
+January 2024 +
+1.7.12 +
+ISG CIM revision and cleanup after TO revision. New keywords +
+February 2024 +
+1.7.13 +
+Footnotes in Tables +
+February 2024 +
+1.7.15 +
+Change of NGSILDTerm style to HTML Keyboard +
+February 2024 +
+1.7.16 +
+Added expiresAt to @context serving +
+March 2024 +
+1.8.1 +
+Published +
+April 2024 +
+1.8.2 +
+Clone of published +
+April 2024 +
+1.8.3 +
+Minor typos and style cleanup +
+April 2024 +
+1.8.3 +
+000048_Fix_operations_allowing_sysAttrs.docx +
+April 2024 +
+1.8.3 +
+000047r2_Accept_header_in_case_of_partial_success__207_.docx +
+April 2024 +
+1.8.3 +
+000049r1_Clarify__options__allowed_for_POST_queries.docx +
+April 2024 +
+1.8.4 +
+Track changes removed +
+May 2024 +
+1.8.5 +
+TooLargeResponse +
+June 2024 +
+1.8.6 +
+CIM(24)000036r1_Loop_Detection +
+June 2024 +
+1.8.7 +
+CIM(24)000033r6_Backwards_Compatibility_Indicators +
+June 2024 +
+1.8.8 +
+CIM(24)000027r5_Value_Type +
+June 2024 +
+1.8.9 +
+CIM(24)000029_Purge_Entities +
+June 2024 +
+1.8.10 +
+CIM(24)000028r4_Transient_Entity_bugfixed +
+June 2024 +
+1.8.11 +
+CIM(24)000070_Additional_Updates_to_ExpiresAt__Conformance_etc_ +
+October 2024 +
+1.8.12 +
+CIM(24)000076r8_Entity_Maps_and_Split_Entities +
+October 2024 +
+1.8.13 +
+CIM(24)000108_Adding_Missing_Elements_in_Core_Context_and_Data_Types.zip +
+October 2024 +
+1.8.14 +
+Updated figures and new baseline and created Stable Draft out of this +
+ + diff --git a/public/22-annex-i-informative-change-history.html b/public/22-annex-i-informative-change-history.html new file mode 100644 index 0000000000000000000000000000000000000000..786b4e479ac4124ee70a1e56c54950a916d0f677 --- /dev/null +++ b/public/22-annex-i-informative-change-history.html @@ -0,0 +1,3556 @@ + + + + + + + Annex I (informative): Change history + + + + + + + +
+

Annex I +(informative):
+Change history

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Date +
+Version +
+Information about changes +
+February 2020 +
+1.2.10 +
+Early draft copied from API version 1.2.1 +
+February 2020 +
+1.2.11 +
+Unicode characters. Query Language syntax changes to Attribute path, and +extension to accept specifying just Query or Geoquery when Querying +Entities +
+
+Acknowledgements to EU projects. Lightweight Figures +
+March 2020 +
+1.2.12 +
+Extending to other interactions the above changes to query entities +interaction +
+
+Changes to ABNF Query Language syntax to access complex objects value of +properties more easily +
+
+Generalized Notification Headers, in order to carry authentication etc., +info +
+
+Novel &option=count and associated Header to indicate number of +Entities in response to a query +
+
+Novel/entityOperations/query and/temporal/entityOperations/query +endpoints to perform query via POST +
+
+Clarified attrs URL parameter behaviour +
+
+Support for Multiple Attributes +
+
+Support for Multiple Tenants +
+May 2020 +
+Candidate 1.2.13 +
+from 101r1: Multi-Attribute-Support-fix-in-4.5.5 +
+
+from 102r1: Batch_Operation_Error_Codes +
+
+from 110r1: JSON-LD Validation clause +
+
+from 112r1: IRI Support for International Characters +
+
+from 115r2: More Core Context Changes +
+
+from 130: Entity Types +
+
+MQTT Notifications +
+
+GeoJSON Representation +
+9 July 2020 +
+1.3.1 +
+Technical Officer verifications for submission to editHelp! publication +pre-processing +
+August 2020 +
+1.3.2 +
+New baseline towards v1.4.1 +
+November 2020 +
+1.3.3 +
+From 272r1: Support for natural languages via LanguageProperty; annex +G +
+December 2020 +
+1.3.4 +
+From 319: Align Table 6.8.3.2‑1 +with clause +5.10.2 for query via attrs +
+December 2020 +
+1.3.4 +
+From 310r2: Dot vs. comma in DateTime +
+December 2020 +
+1.3.4 +
+From 309r1: Remove sentences referring to old multi attributes +representation +
+December 2020 +
+1.3.4 +
+From 308r: id and type for JSON-LD compliance +
+December 2020 +
+1.3.4 +
+From 313r1: FIXES to Cross domain data model for LanguageProperties +
+
+Bug fixes and errata +
+December 2020 +
+1.3.5 +
+From 275r3: Temporal Aggregation Functions +
+December 2020 +
+1.4.0 +
+1.3.5 with small typos corrected, approved as 1.4.0 +
+January 2021 +
+1.4.1 +
+ETSI Technical Officer review for ETSI EditHelp publication +pre-processing +
+March 2021 +
+1.4.2 +
+Editorial Changes, clarifications added, better references, figures +replacements and corrections, figures merged, typos, code identation +
+April 2021 +
+1.4.2 +
+Temporal Pagination +
+April 2021 +
+1.4.2 +
+Clarified behavior when multiple instances of the same Entity are in an +input array +
+July 2021 +
+1.4.3 +
+From 130r6: NGSI-LD Scope +
+July 2021 +
+1.4.3 +
+From 143r6: Storing, managing and serving @contexts +
+July 2021 +
+1.4.3 +
+From 120r4: API structuring +
+October 2021 +
+1.4.4 +
+From 156: Remove static elements from temporal representations +
+October 2021 +
+1.4.4 +
+From 155: Existence query +
+October 2021 +
+1.4.4 +
+From 152: Remove null value deletion +
+October 2021 +
+1.4.4 +
+From 151: attrs missing in core context +
+October 2021 +
+1.5.1 +
+ETSI Technical Officer review for ETSI EditHelp publication +pre-processing +
+November 2021 +
+1.5.2 +
+First early draft after EditHelp publication of V1.5.1 to prepare next +V1.6.1 publication +
+January 2022 +
+1.5.3 +
+Concise representation +
+May 2022 +
+1.5.4 +
+PUT/PATCH Entity +
+May 2022 +
+1.5.4 +
+Distributed operations +
+July 2022 +
+1.5.5 +
+From 99r6: Deletions and advanced notifications +
+July 2022 +
+1.5.5 +
+From 106r1: Workflow for actuation +
+July 2022 +
+1.5.5 +
+From 105r1: Context Source Info in Context Source Registration +
+July 2022 +
+1.5.5 +
+From 93r1: default context clarification +
+July 2022 +
+1.5.5 +
+From 91r1: CR_on_Scope_ABNF_format +
+Juy 2022 +
+1.6.1 +
+Final Technical Official check for EditHelp publication +
+October 2022 +
+1.6.2 +
+New early draft: +
+
+corrected Annex +C6 date representation +
+
+from 149r3: generalized description of @context in bullet lists +
+
+Fixed usage of NGSI-LD Null in Attributes’ definitions +
+December 2022 +
+1.6.4 +
+From 188r2_Registration_Clarifications +
+December 2022 +
+1.6.4 +
+From 182r2_Add_NGSI-LD_Roles_for_Context_Registration +
+December 2022 +
+1.6.4 +
+From 156r2 VocabProperty/URI type coercion +
+December 2022 +
+1.6.4 +
+177r2 Clarify usage of Accept, Content-Type and Linked @context when +forwarding to partial Context Brokers +
+December 2022 +
+1.6.4 +
+178 Add Batch Query to Federation Ops +
+December 2022 +
+1.6.4 +
+183r1 Clarify Temporal query behaviour +
+December 2022 +
+1.6.4 +
+149r4 Forbid scoped and nested @contexts +
+December 2022 +
+1.6.4 +
+023006 Fixing CSource registration example in C.3 +
+December 2022 +
+1.6.4 +
+Fix: Tenants URI becomes String +
+December 2022 +
+1.6.4 +
+Fix: POST-QUERY-COUNT-PAGINATION +
+December 2022 +
+1.6.4 +
+Fix: CHECK-URI-PARAM +
+December 2022 +
+1.6.4 +
+Updated examples and text to context v1.7.jsonld +
+March 2023 +
+1.6.6 +
+CIM(23)000006_Adding_previousValue_to_GeoProperty_type_definition +
+March 2023 +
+1.6.6 +
+cSource -> CSource; “implementations shall do the following” +
+March 2023 +
+1.6.7 +
+000013r4_Updated_Distributed_Execution_Behaviour +
+March 2023 +
+1.6.8 +
+CIM(22)000195r3_type_passing_for_M2M_callReviewed +
+April 2023 +
+1.6.9 +
+Fixing URI🡪String datatypes +
+June 2023 +
+1.7.2 +
+CIM(23)000053r1_Entity_Graph_Retrieval (for FIWARE SUMMIT) +
+June 2023 +
+1.7.3 +
+000056r2_APIv172_towards_v18.docx (for FIWARE SUMMIT) +
+October 2023 +
+1.7.4 +
+From 25023r2: Use Temporal Evolution instead of Temporal Representation ++ Updated figures in clause +5 and 6 +
+November 2023 +
+1.7.5 +
+From 68r5: Additional id only format and attribute projection via pick +and omit +
+
+From 121r1: Relationship as Array +
+
+From 123r1: URN Namespace Definitions +
+
+From 149r3: Allow Broader Local Requests +
+
+From 153r1: JsonProperty +
+
+From 159: Bug fixed in CIM 009: GeoJSON responses in figures +
+
+From 160: Replace Attribute fix +
+December 2023 +
+1.7.6 +
+From 164: Host alias /info Endpoint +
+
+From 154r2: EntityMap +
+
+Updated figure in clause +6.2 +
+January 2024 +
+1.7.7 +
+From 168r1: 504 error instead of 503 in JSON-LD context endpoints +
+
+From 169r1: Allow forbidden characters +
+
+From 170: Remove Scope from PATCH /attrs operations +
+
+From 1005r2: URI for value of several attributes +
+
+From 173r2: Clarify match in distributed operations +
+
+From 174: Protect core context +
+
+From 25002r2: API Issue #10 Filter on value with specific datasetId +
+January 2024 +
+1.7.8 +
+From 164r5: fix Tenant in Host Alias (164) and /info/sourceIdentity +Endpoint + figure +
+
+Updated figure in clause +6.2 +
+
+Updated figures in clause +4.2 +
+January 2024 +
+1.7.9 +
+CIM(24)000007r2_Query_Language_Extension_for_Linked_Entity_Retrieval +
+January 2024 +
+1.7.10 +
+Internal revision, cleanup +
+January 2024 +
+1.7.10 +
+FIX: CIM(24)000015_Projection_attributes_error_messaging +
+January 2024 +
+1.7.10 +
+FIX: CIM(24)000014r1_POST_Query_Parameters +
+January 2024 +
+1.7.11 +
+TO revision +
+January 2024 +
+1.7.12 +
+ISG CIM revision and cleanup after TO revision. New keywords +
+February 2024 +
+1.7.13 +
+Footnotes in Tables +
+February 2024 +
+1.7.13 +
+Change of NGSILDTerm style to +
+
+ + diff --git a/public/22-history.html b/public/22-history.html new file mode 100644 index 0000000000000000000000000000000000000000..65a500632f6994d38a812fc85f1b61c2967f80f2 --- /dev/null +++ b/public/22-history.html @@ -0,0 +1,2945 @@ + + + + + + + History + + + + + + + + +

History

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Document history +
+
+V1.1.1 +
+
+
+January 2019 +
+
+
+Publication +
+
+
+V1.2.1 +
+
+
+October 2019 +
+
+
+Publication +
+
+
+V1.2.2 +
+
+
+February 2020 +
+
+
+Publication +
+
+
+V1.3.1 +
+
+
+August 2020 +
+
+
+Publication +
+
+
+V1.4.1 +
+
+
+February 2021 +
+
+
+Publication +
+
+
+V1.4.2 +
+
+
+April 2021 +
+
+
+Publication +
+
+
+V1.5.1 +
+
+
+November 2021 +
+
+
+Publication +
+
+
+V1.6.1 +
+
+
+August 2022 +
+
+
+Publication +
+
+
+V1.7.1 +
+
+
+June 2023 +
+
+
+Publication +
+
+
+V1.8.1 +
+
+
+March 2024 +
+
+
+Publication +
+
+ + diff --git a/public/23-history.html b/public/23-history.html new file mode 100644 index 0000000000000000000000000000000000000000..97c23e028c4d4ddfd65ecc5d3104db776f4cd1b9 --- /dev/null +++ b/public/23-history.html @@ -0,0 +1,2802 @@ + + + + + + + History + + + + + + + +
+

History

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Document history +
+
+V1.1.1 +
+
+
+January 2019 +
+
+
+Publication +
+
+
+V1.2.1 +
+
+
+October 2019 +
+
+
+Publication +
+
+
+V1.2.2 +
+
+
+February 2020 +
+
+
+Publication +
+
+
+V1.3.1 +
+
+
+August 2020 +
+
+
+Publication +
+
+
+V1.4.1 +
+
+
+February 2021 +
+
+
+Publication +
+
+
+V1.4.2 +
+
+
+April 2021 +
+
+
+Publication +
+
+
+V1.5.1 +
+
+
+November 2021 +
+
+
+Publication +
+
+
+V1.6.1 +
+
+
+August 2022 +
+
+
+Publication +
+
+
+V1.7.1 +
+
+
+April 2023 +
+
+
+Publication +
+
+
+ + diff --git a/public/3-foreword.html b/public/3-foreword.html new file mode 100644 index 0000000000000000000000000000000000000000..f31fd37b109108a9e1d65a622861c660a609f000 --- /dev/null +++ b/public/3-foreword.html @@ -0,0 +1,2637 @@ + + + + + + + Foreword + + + + + + + +
+

Foreword

+

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

+
+ + diff --git a/public/3-modal-verbs-terminology.html b/public/3-modal-verbs-terminology.html new file mode 100644 index 0000000000000000000000000000000000000000..33d3a9695559c2b423df7a419874d08a23d09a26 --- /dev/null +++ b/public/3-modal-verbs-terminology.html @@ -0,0 +1,2772 @@ + + + + + + + Modal verbs terminology + + + + + + + + +

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.

+ + diff --git a/public/4-executive-summary.html b/public/4-executive-summary.html new file mode 100644 index 0000000000000000000000000000000000000000..7a0787f6d43edb3ebee9e72003db776b2914607d --- /dev/null +++ b/public/4-executive-summary.html @@ -0,0 +1,2770 @@ + + + + + + + Executive summary + + + + + + + + +

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

+ + diff --git a/public/4-modal-verbs-terminology.html b/public/4-modal-verbs-terminology.html new file mode 100644 index 0000000000000000000000000000000000000000..3e49dce099ff07c8764fc1aac01a2754aa25315c --- /dev/null +++ b/public/4-modal-verbs-terminology.html @@ -0,0 +1,2646 @@ + + + + + + + Modal verbs terminology + + + + + + + +
+

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.

+
+ + diff --git a/public/5-executive-summary.html b/public/5-executive-summary.html new file mode 100644 index 0000000000000000000000000000000000000000..ed4a31c11a97ab8b3733e1082857696a3f9f9dbf --- /dev/null +++ b/public/5-executive-summary.html @@ -0,0 +1,2643 @@ + + + + + + + Executive summary + + + + + + + +
+

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

+
+ + diff --git a/public/5-introduction.html b/public/5-introduction.html new file mode 100644 index 0000000000000000000000000000000000000000..ec3e1036bd9dc3a69542691ce49e8c0076ba33ae --- /dev/null +++ b/public/5-introduction.html @@ -0,0 +1,2785 @@ + + + + + + + Introduction + + + + + + + + +

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.

+ + diff --git a/public/6-introduction.html b/public/6-introduction.html new file mode 100644 index 0000000000000000000000000000000000000000..f9bf8e1279a952c69214896eae3821d501af10e3 --- /dev/null +++ b/public/6-introduction.html @@ -0,0 +1,2658 @@ + + + + + + + Introduction + + + + + + + +
+

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.

+
+ + diff --git a/public/6-tabscope.html b/public/6-tabscope.html new file mode 100644 index 0000000000000000000000000000000000000000..26b7fd7a7163f72000e72f93d673e0ea72d32e5e --- /dev/null +++ b/public/6-tabscope.html @@ -0,0 +1,2777 @@ + + + + + + + 1 Scope + + + + + + + + +

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

+ + diff --git a/public/7-tabreferences.html b/public/7-tabreferences.html new file mode 100644 index 0000000000000000000000000000000000000000..645576a6abd89aece082491c4d578e6c31d24b98 --- /dev/null +++ b/public/7-tabreferences.html @@ -0,0 +1,3319 @@ + + + + + + + 2 References + + + + + + + + +

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

+
+
+NOTE: +
+
+While + +any + +hyperlinks + +included + +in + +this + +clause + +were + +valid + +at + +the + +time + +of + +publication, + +ETSI + +cannot + +guarantee + +their + +long-term + +validity. +
+
+

The following referenced documents are necessary for the application +of the present document.

+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+[33] IETF RFC 6906: +"The 'profile' Link Relation Type". +
+
+
+ +
+
+ +
+
+

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.

+
+
+NOTE: +
+
+While + +any + +hyperlinks + +included + +in + +this + +clause + +were + +valid + +at + +the + +time + +of + +publication, + +ETSI + +cannot + +guarantee + +their + +long-term + +validity. +
+
+

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.

+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+
+
+ +
+
+ +
+
+ + diff --git a/public/7-tabscope.html b/public/7-tabscope.html new file mode 100644 index 0000000000000000000000000000000000000000..950963cdb740a0ab6ed87d25f2717f6f05447264 --- /dev/null +++ b/public/7-tabscope.html @@ -0,0 +1,2651 @@ + + + + + + + 1 Scope + + + + + + + +
+

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

+
+ + diff --git a/public/8-tabdefinition-of-terms-symbols-and-abbreviations.html b/public/8-tabdefinition-of-terms-symbols-and-abbreviations.html new file mode 100644 index 0000000000000000000000000000000000000000..9ed6259f7261dfd7ac9604a08a281b0f7d892b71 --- /dev/null +++ b/public/8-tabdefinition-of-terms-symbols-and-abbreviations.html @@ -0,0 +1,4331 @@ + + + + + + + 3 Definition of terms, symbols and +abbreviations + + + + + + + + +

3 Definition of +terms, symbols and abbreviations

+

3.1 Terms

+

For the purposes of the present document, the following terms +apply:

+
+
+NOTE 1: +
+
+The + +letters + +"NGSI-LD" + +were + +added + +to + +most + +terms + +to + +confirm + +that + +they + +are + +distinct + +from + +other + +terms + +of + +similar/same + +name + +in + +use + +in + +other + +organizations, + +however, + +in + +the + +present + +document + +the + +letters + +"NGSI-LD" + +are + +generally + +omitted + +for + +brevity. +
+
+
+
+NOTE 2: +
+
+The + +use + +of + +URI + +in + +the + +context + +of + +the + +present + +document + +also + +includes + +the + +use + +of + +International + +Resource + +Identifiers + +(IRIs) + +as + +defined + +in + +IETF + +RFC + +3987 + +[23], + +which + +extends + +the + +use + +of + +characters + +to + +Unicode + +characters + +[22] + +beyond + +the + +ASCII + +character + +set, + +enabling + +the + +support + +of + +languages + +other + +than + +English. +
+
+

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

+
+
+NOTE: +
+
+It + +is + +used + +by + +Distribution Brokers + +and + +Federation Brokers + +to + +find + +the + +appropriate + +Context Sources + +which + +can + +provide + +the + +information + +required + +for + +serving + +an + +NGSI-LD + +request. +
+
+

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

+
+
+NOTE: +
+
+It + +is + +usually + +registered + +with + +an + +NGSI-LD + +Registry + +so + +that + +it + +can + +announce + +what + +kind + +of + +information + +it + +can + +provide, + +when + +requested, + +to + +Context Consumers + +and + +Brokers. +
+
+

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

+
+
+NOTE: +
+
+In + +the + +NGSI-LD + +API, + +any + +instance + +of + +such + +an + +entity + +is + +uniquely identified by a URI +, + +and + +characterized + +by + +reference + +to + +one + +or + +more + +NGSI-LD Entity Type(s) +. +
+
+

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 Entity Type: categorization of an NGSI-LD +Entity as belonging to a class of similar entities, or sharing a set of +characteristic properties

+
+
+NOTE: +
+
+In + +the + +NGSI-LD + +API, + +an + +NGSI-LD + +Entity + +Type + +is + +uniquely identified by a URI +. +
+
+
+
+EXAMPLE 1: +
+
+ +"Vehicle" + +is + +an + +NGSI-LD + +Entity + +Type + +and + +is + +identified + +with + +a + +proper + +URI. +
+
+
+
+EXAMPLE 2: +
+
+Bob's + +private + +car + +whose + +plate + +number + +is + +"ABCD1234" + +is + +an + +NGSI-LD + +Entity + +whose + +NGSI-LD + +Entity + +Type + +name + +is + +"Vehicle" +. +
+
+
+
+EXAMPLE 3: +
+
+Alice's + +motorhome + +has + +a + +unique + +URI + +as + +id, + +but + +can + +be + +assigned + +multiple + +NGSI-LD + +Entity + +types, + +e.g. + +"Vehicle" + +and + +"Home" +. +
+
+

NGSI-LD External Linked Entity: Linked Entity that is identified through a +dereferenceable URI which does not exist within the +current NGSI-LD system

+
+
+NOTE: +
+
+It + +can + +exist + +within + +another + +NGSI-LD + +system + +or + +within + +a + +non-NGSI-LD + +system. +
+
+
+
+EXAMPLE: +
+
+An + +NGSI-LD + +Entity, + +whose + +Entity + +Type + +name + +is + +"Book" +, + +can + +be + +externally + +linked, + +through + +the + +"wasWrittenBy" + +relationship, + +to + +a + +resource + +identified + +by + +the + +URI + +"http://dbpedia.org/resource/Mark_Twain" +. +
+
+

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

+
+
+EXAMPLE: +
+
+An + +NGSI-LD + +Entity, + +whose + +Entity + +Type + +name + +is + +"Vehicle", + +can + +be + +internally + +linked, + +through + +the + +"isParkedAt" +relationship, + +to + +another + +NGSI-LD + +Entity, + +of + +Type + +name + +"Parking" +, + +identified + +by + +the + +URI + +"urn:ngsi-ld:Parking:Downtown1" +. +
+
+

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

+
+
+NOTE: +
+
+The + +target + +value + +contains + +data + +which + +is + +not + +available + +for + +interpretation. +
+
+

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

+
+
+EXAMPLE: +
+
+"A + +bus + +route + +services + +the + +following + +bus + +stops" + +can + +be + +represented + +by + +an + +NGSI-LD + +ListRelationship + +whose + +name + +is + +"route" + +which + +holds + +an + +array + +of + +directed + +links + +towards + +a + +series + +of + +NGSI-LD + +Entities + +of + +type + +(Type + +name) + +"BusStop" +. +
+
+

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

+
+
+EXAMPLE: +
+
+"Bob's + +vehicle + +is + +currently + +parked + +on + +a + +street + +which + +is + +known + +as + +'Grand + +Place' + +in + +French + +and + +'Grote + +Markt' + +in + +Dutch" + +can + +be + +represented + +by + +an + +NGSI-LD + +LanguageProperty + +whose + +name + +is + +"street" + +which + +holds + +an + +NGSI-LD + +Map + +of + +two + +key-value + +pairs + +containing + +both + +the + +French + +("fr" +) + +and + +Dutch + +( +"nl" +) + +exonyms + +of + +the + +street + +name. +
+
+

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

+
+
+EXAMPLE: +
+
+"Bob's + +vehicle's + +speed + +is + +40 + +km/h" + +can + +be + +represented + +by + +an + +NGSI-LD + +Property, + +whose + +name + +is + +"speed", + +and + +which + +characterizes + +an + +NGSI-LD + +Entity, + +whose + +NGSI-LD + +Type + +is + +"Vehicle" +. + +Such a name can be expanded to +a fully qualified name in the form of a +URI +, for instance +"http://example.org/Vehicle" + +or + +"http://example.org/speed" +. +
+
+

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

+
+
+EXAMPLE 1: +
+
+An + +NGSI-LD + +Entity + +of + +type + +"Vehicle" + +can + +be + +the + +subject + +of + +an + +NGSI-LD + +Relationship + +whose + +object + +is + +an + +NGSI-LD + +Entity + +of + +type + +"Parking" +. +
+
+
+
+EXAMPLE 2: +
+
+An + +NGSI-LD + +Entity + +of + +type + +"Vehicle" + +can + +be + +the + +subject + +of + +an + +NGSI-LD + +Relationship + +whose + +object + +is + +an + +array + +of + +NGSI-LD + +Entities + +of + +type + +"Passenger" +. +
+
+

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)

+
+
+EXAMPLE: +
+
+Bob's + +private + +car + +'speed' + +NGSI-LD + +Value + +is + +the + +number + +100 + +(kilometres + +per + +hour). +
+
+

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

+
+
+EXAMPLE: +
+
+"Bob's + +car + +is + +a + +non-commercial + +vehicle" + +can + +be + +represented + +by + +an + +NGSI-LD + +VocabProperty + +whose + +name + +is + +"category" + +which + +holds + +the + +string + +value + +"non-commercial" +. + +If + +the + +associated + +JSON-LD + +context + +defines + +the + +term + +"non-commercial" +as + +"http://example.com/non-commercial", + +then + +the + +returned + +value + +shall + +be + +expanded + +using + +JSON-LD + +type + +coercion + +into + +the + +URI + +the + +" +http://example.com/non-commercial +" +. +
+
+

3.2 Symbols

+

Void.

+

3.3 Abbreviations

+

For the purposes of the present document, the following abbreviations +apply:

+
+ABNF Augmented Backus-Naur Form +
+
+ALG1 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document +
+
+AM Ante Meridiem +
+
+API Application Programming Interface +
+
+ASCII American Standard Code for Information Interchange +
+
+BNF Backus Naur Form +
+
+CH Switzerland +
+
+CSR Context Source Registration +
+
+ECMA European Computer Manufacturers Association +
+
+EU European Union +
+
+FI Future Internet +
+
+FQN Fully Qualified Name +
+
+GB Great Britain +
+
+GDPR General Data Protection Regulation +
+
+GeoJSON Geographic JavaScript Object Notation +
+
+GeoJSON-LD Geographic JavaScript Object Notation - Linked Data +
+
+GIS Geographic Information System +
+
+GPS Global Positioning System +
+
+HTTP Hypertext Transfer Protocol +
+
+HTTPS Hypertext Transfer Protocol Secure +
+
+IANA Internet Assigned Numbers Authority +
+
+ID Identifier +
+
+IEEE Institute of Electrical and Electronics Engineers +
+
+IETF Internet Engineering Task Force +
+
+IoT Internet of Things +
+
+IRI Internationalized Resource Identifier +
+
+ISG Industry Specification Group +
+
+ISO International Organization for Standardization +
+
+JSON JavaScript Object Notation +
+
+JSON-LD JSON Linked Data +
+
+LD Linked Data +
+
+LWM2M LightWeight Machine to Machine +
+
+M2M Machine to Machine +
+
+MIME Multi-purpose Internet Mail Extensions +
+
+MQTT Message Queuing Telemetry Transport +
+
+N/A Not Applicable +
+
+NGSI Next Generation Service Interfaces +
+
+NGSILD Next Generation Service +Interfaces Linked Data (same as NGSI-LD) +
+
+NID Namespace Identifier +
+
+NSS Namespace Specific String +
+
+OAS Open API Specification +
+
+OMA Open Mobile Alliance +
+
+oneM2M oneM2M Partnership Project +
+
+PM Post Meridiem +
+
+POSIX Portable Operating System Interface +
+
+QoS Quality of Service +
+
+RDF Resource Description Format +
+
+REST Representational State Transfer +
+
+RFC Request For Comments +
+
+SAREF Smart Applications REFerence ontology +
+
+TCP Transport Control Protocol +
+
+TLS Transport Layer Security +
+
+TS Technical Specification +
+
+UCA Unicode Collation Algorithm +
+
+UL Ultra Light +
+
+UML Unified Modelling Language +
+
+URI Uniform Resource Identifier +
+
+URL Universal Resource Locator +
+
+URN Uniform Resource Name +
+
+UTC Coordinated Universal Time +
+
+UTF Unicode (or Universal Coded Character Set) Transformation Format +
+
+
+ +
+
+ +
+
+ + diff --git a/public/8-tabreferences.html b/public/8-tabreferences.html new file mode 100644 index 0000000000000000000000000000000000000000..94a049c0d1fae08fd78066424b1f231df90776d9 --- /dev/null +++ b/public/8-tabreferences.html @@ -0,0 +1,2923 @@ + + + + + + + 2 References + + + + + + + +
+

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

+
+NOTE: While any hyperlinks included in this clause were valid at the time +of publication, ETSI cannot guarantee their long-term validity. +
+

The following referenced documents are necessary for the application +of the present document.

+
+[1] W3C® Recommendation 25 February 2014: "RDF Schema +1.1". +
+
+[2] W3C® Recommendation 16 July 2020: "JSON-LD 1.1 - A JSON-based +Serialization for Linked Data". +
+
+[3] IETF RFC 7231: +"Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content". +
+
+[4] IETF RFC 7232: +"Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests". +
+
+[5] IETF RFC 3986: +"Uniform Resource Identifier (URI): Generic Syntax". +
+
+[6] IETF RFC 8259: +"The JavaScript Object Notation (JSON) Data Interchange Format". +
+
+[7] IETF RFC 8288: +"Web Linking". +
+
+[8] IETF RFC 7946: +"The GeoJSON Format". +
+
+[9] IETF RFC 8141: +"Uniform Resource Names (URNs)". +
+
+[10] IETF RFC 7807: +"Problem Details for HTTP APIs". +
+
+[11] IEEE +1003.2™-1992: "IEEE Standard for Information Technology - Portable +Operating System Interfaces (POSIX™) - Part 2: Shell and Utilities". +
+
+[12] IETF RFC 5234: +"Augmented BNF for Syntax Specifications: ABNF". +
+
+[13] Unicode® +Technical Standard #10: "Unicode Collation Algorithm". +
+
+[14] Open +Geospatial Consortium Inc. OGC 06-103r4: "OpenGIS® +Implementation Standard for Geographic information - Simple feature +access - Part 1: Common architecture". +
+ +
+[16] IETF RFC 7396: +"JSON Merge Patch". +
+
+[17] ISO 8601: +2004: "Data elements and interchange formats -- Information +interchange -- Representation of dates and times". +
+
+[18] IETF RFC 2818: +"HTTP Over TLS". +
+
+[19] IETF RFC 5246: +"The Transport Layer Security (TLS) Protocol Version 1.2". +
+ +
+[21] ECMA 262 Specification: "ECMAScript® +2022 language specification". +
+
+[22] The Unicode Consortium: "The Unicode +Standard". +
+
+[23] IETF RFC 3987: +"Internationalized Resource Identifiers (IRIs)". +
+
+[24] OASIS Standard: "MQTT +Version 3.1.1 Plus Errata 01". Edited by Andrew Banks and Rahul +Gupta. 10 December 2015. +
+
+[25] OASIS Standard: "MQTT +Version 5.0". Edited by Andrew Banks, Ed Briggs, Ken Borgendale and +Rahul Gupta. 07 March 2019. +
+
+[26] IETF RFC 7240: +"Prefer Header for HTTP". +
+
+[27] IETF RFC 7230: +"Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing". +
+
+[28] IETF RFC 5646: +"Tags for Identifying Languages". +
+
+[29] IETF RFC 3282: +"Content Language Headers". +
+
+[30] IETF RFC 7234: +"Hypertext Transfer Protocol (HTTP/1.1): Caching". +
+
+[31] IETF RFC 7233: +"Hypertext Transfer Protocol (HTTP/1.1): Range Requests". +
+ +

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.

+
+NOTE: While any hyperlinks included in this clause were valid at the time +of publication, ETSI cannot guarantee their long-term validity. +
+

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.

+
+[i.1] ETSI +GR CIM 002 (V1.1.1): "Context Information Management (CIM); Use +Cases (UC)". +
+
+[i.2] ETSI GR CIM +007: "Context Information Management (CIM); Security and Privacy". +
+
+[i.3] OMA-TS-NGSI_Context_Management-V1_0-20120529-A: +"NGSI Context Management". +
+
+[i.4] ETSI TS 103 264 (V3.1.1): "SmartM2M; Smart Applications; Reference +Ontology and oneM2M Mapping". +
+
+[i.5] NGSI-LD +Wrapper. +Experimental proxy for adaptation between FIWARE® and NGSI-LD. +
+
+[i.6] Graph Databases: "New Opportunities for Connected Data". O'Reilly +2nd Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892. +
+
+[i.7] JSON-LD +Playground. +Experimentation tool for JSON-LD. +
+
+[i.8] ETSI GS CIM +006: "Context Information Management (CIM); Information Model +(MOD0)". +
+ +
+[i.10] IETF RFC +6902: "JavaScript Object Notation (JSON) Patch". +
+ + + + +
+[i.15] NGSI-LD +Examples. +
+
+[i.16] ETSI GS CIM 004 (V1.1.2): "Context Information Management (CIM); +Application Programming Interface (API)". +
+
+[i.17] ETSI ISG CIM: "NGSI-LD +Status". +
+
+[i.18] Regulation +(EU) 2016/679 of the European Parliament and of the Council of 27 +April 2016 on the protection of natural persons with regard to the +processing of personal data and on the free movement of such data, and +repealing Directive +95/46/EC (General Data Protection Regulation). +
+
+[i.19] MQTT URI +Scheme. +
+
+[i.20] GeoJSON-LD 1.0: Base context for processing +GeoJSON according to the JSON-LD processing model. +
+
+[i.21] ETSI GR CIM +008: "Context Information Management (CIM); NGSI-LD Primer". +
+
+[i.22] IoT +Agent Library. +
+
+ + diff --git a/public/9-tabcontext-information-management-framework.html b/public/9-tabcontext-information-management-framework.html new file mode 100644 index 0000000000000000000000000000000000000000..9b358b16793db5aa57fa72ab549a829d385997b0 --- /dev/null +++ b/public/9-tabcontext-information-management-framework.html @@ -0,0 +1,15570 @@ + + + + + + + 4 Context Information Management Framework + + + + + + + + +

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.

+
+ +
+
+Figure 4.2.1-1: Overview of the NGSI-LD Information Model Structure +
+

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.

+
+ +
+
+Legend: +
+
+ +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+[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.2-1: NGSI-LD Core Meta-Model +
+

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

+
+ +
+
+Legend: +
+
+ +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+[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: NGSI-LD Core Meta-Model plus the Cross-Domain 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".

+
+ +
+
+Figure 4.2.4-1: Cross-Domain Ontology and instantiation +
+

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.

+
+ +
+
+Figure 4.2.5-1: NGSI-LD information model as UML +
+

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 NGSI-LD API implicitly defines two sets of Entities: +
+
    +
  • +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.

+
+ +
+
+Figure 4.3.2-1: Centralized architecture +
+

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.

+
+ +
+
+Figure 4.3.3-1: Distributed architecture +
+

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.

+
+ +
+
+Figure 4.3.4-1: Federated architecture +
+

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. To support the +distributed and federated architectures described in clauses 4.3.3 +and 4.3.4 +respectively, distributed versions of the operations are needed. They +are listed separately under Distributed API and require the operations +of the Registry API. 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. The distributed versions of the operations +are separately shown in Table +4.3.5‑1 under Distributed API, but there is a single clause for each +of the operations describing both the centralized and distributed +behaviour. In addition, the Distributed API has support operations only +needed in distributed and federated architectures.

+
+Table 4.3.5-1: NGSI-LD API structure +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+API +
+Functionality +
+Operations +
+Core API +
+Context Information Provision - operations for providing or managing +Entities and Attributes +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
Context Information Consumption +- operations for consuming Entities and checking for which Entity Types +and Attributes Entities are available in the system
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
Context Information Subscription +- operations for subscribing to Entities, receiving notifications and +managing subscriptions
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+
+5.8.6 Notification +
+Temporal API +
Temporal Context Information +Provision - operations for providing or managing the Temporal Evolution of +Entitiesand +Attributes
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
Temporal Context Information +Consumption - operations for consuming the Temporal Evolution of +Entities
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
Distributed APIDistributed Context Information Provision +– operations for providing or managing Entities and Attributes

5.6.1 Create Entity (distributed)

+

5.6.2 Update Attributes (distributed)

+

5.6.3 Append Attributes (distributed)

+

5.6.4 Partial Attribute Update (distributed)

+

5.6.5 Delete Attribute (distributed)

+

5.6.6 Delete Entity (distributed)

+

5.6.7 Batch Entity Creation (distributed)

+

5.6.8 Batch Entity Upsert (distributed)

+

5.6.9 Batch Entity Update (distributed)

+

5.6.10 Batch Entity Delete (distributed)

+

5.6.17 Merge Entity (distributed)

+

5.6.18 Replace Entity (distributed)

+

5.6.19 Replace Attribute (distributed)

+

5.6.20 Batch Entity Merge (distributed)

Distributed Context Information +Consumption - operations for consuming Entities and checking for which +Entity Types and Attributes Entities are available in the system

5.7.1 Retrieve Entity (distributed)

+

5.7.2 Query Entities (distributed)

+

5.7.5 Retrieve Available Entity Types (distributed)

+

5.7.6 Retrieve Details of Available Entity Types (distributed)

+

5.7.7 Retrieve Available Entity Type Information (distributed)

+

5.7.8 Retrieve Available Attributes (distributed)

+

5.7.9 Retrieve Details of Available Attributes (distributed)

+

5.7.10 Retrieve Available Attribute Information +(distributed)

Distributed Context Information +Subscription - operations for subscribing to Entities, receiving +notifications and managing subscriptions

5.8.1 Create Subscription (distributed)

+

5.8.2 Update Subscription (distributed)

+

5.8.3 Retrieve Subscription (distributed)

+

5.8.4 Query Subscription (distributed)

+

5.8.5 Delete Subscription (distributed)

+

5.8.6 Notification (distributed)

Distributed Temporal Context Information +Provision - operations for providing or managing the Temporal Evolution +of Entities and Attributes

5.6.11 Upsert Temporal Evolution of an Entity (distributed)

+

5.6.12 Add Attributes to Temporal Evolution of an Entity +(distributed)

+

5.6.13 Delete Attributes from Temporal Evolution of an Entity +(distributed)

+

5.6.14 Partial Update Attribute instance (distributed)

+

5.6.15 Delete Attribute Instance (distributed)

+

5.6.16 Delete Temporal Evolution of an Entity (distributed)

Distributed Temporal Context Information +Consumption - operations for consuming the Temporal Evolution of +Entities

5.7.3 Retrieve Temporal Evolution of an Entity (distributed)

+

5.7.4 Query Temporal Evolution of Entities (distributed)

Support operations for distributed +operations

5.14.1 Retrieve EntityMap

+

5.14.2 Update EntityMap

+

5.14.3 Delete EntityMap

+

5.14.4 Create EntityMap for Query Entities

+

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

+

5.15.1 Retrieve Context Source Identity Information

+Registry API +
Context Source +Registration- +operations for registering Context Sourcesand managing Context Source +Registrations(CSRs)
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
Context SourceDiscovery - operations for +retrieving and discovering CSRs
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
Context Source +RegistrationSubscription - operations for +subscribing to CSRs, receiving notifications and managing +CSRs
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+
+5.11.7 CSR Notification +
JSONLDContext APIStoring, managing and serving +@contexts
+5.13.2 Add @context +
+
+5.13.3 List @contexts +
+
+5.13.4 Serve @context +
+
+5.13.5 Delete and Reload @context +
+

All Context Brokers shall +implement the Core API. Context +Brokers supporting distributed and federated deployments shall also +implement the Distributed 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-2: Main implementation configurations +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Description +
+Temporal API +
+Registry API +
+Central Broker without temporal support +
+none +
+none +
+Central Broker with integrated temporal component +
+local +
+none +
+Central Broker with separate temporal component +
+separate +
+none +
+Context Broker supporting distributed and federated deployments without +temporal support and with integrated Context Registry +
+none +
+local +
+Context Broker supporting distributed and federated deployments with +integrated temporal component and integrated Context Registry +
+local +
+local +
+Context Broker supporting distributed and federated deployments with +separate temporal component and integrated Context Registry +
+separate +
+local +
+Context Broker supporting distributed and federated deployments without +temporal support and separate Context Registry +
+none +
+separate +
+Context Broker supporting distributed and federated deployments with +integrated temporal component and separate Context Registry +
+local +
+separate +
+Context Broker supporting distributed and federated deployments with +separate temporal component and separate Context Registry +
+separate +
+separate +
+

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.

+
+Table 4.3.5-3: Operations implemented by the various NGSI-LD Roles +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+NGSI-LD Role +
+Implements +
+Uses +
+Context Consumer +
+5.8.6 Notification - if supporting asynchronous +interactions +
+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.11.7 CSR Notification - if supporting asynchronous +interactions +
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
+
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+

5.14.1 Retrieve EntityMap

+

5.14.2 Update EntityMap

+

5.14.3 Delete EntityMap

+

5.14.4 Create EntityMap for Query Entities

+

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

+

5.15.1 Retrieve Context Source Identity Information

+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+ if supporting asynchronous interactions: +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+Context Producer +
+none +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
+Context Source +
+5.7.1 Retrieve Entity +
+
+5.7.2 Query Entities +
+
+5.7.5 Retrieve Available Entity Types +
+
+5.7.6 Retrieve Details of Available Entity Types +
+
+5.7.7 Retrieve Available Entity Type Information +
+
+5.7.8 Retrieve Available Attributes +
+
+5.7.9 Retrieve Details of Available Attributes +
+
+5.7.10 Retrieve Available Attribute Information +
+
+5.8.1 Create Subscription +
+
+5.8.2 Update Subscription +
+
+5.8.3 Retrieve Subscription +
+
+5.8.4 Query Subscription +
+
+5.8.5 Delete Subscription +
+

5.14.1 Retrieve EntityMap

+

5.14.2 Update EntityMap

+

5.14.3 Delete EntityMap

+

5.14.4 Create EntityMap for Query Entities

+

5.14.5 Create EntityMap for Query Temporal Evolution of Entities

+
+5.15.1 Retrieve Context Source Identity Information +
+5.8.6 Notification +
+
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+Context Repository +
+5.6.1 Create Entity +
+
+5.6.2 Update Attributes +
+
+5.6.3 Append Attributes +
+
+5.6.4 Partial Attribute Update +
+
+5.6.5 Delete Attribute +
+
+5.6.6 Delete Entity +
+
+5.6.7 Batch Entity Creation +
+
+5.6.8 Batch Entity Upsert +
+
+5.6.9 Batch Entity Update +
+
+5.6.10 Batch Entity Delete +
+
+5.6.17 Merge Entity +
+
+5.6.18 Replace Entity +
+
+5.6.19 Replace Attribute +
+
+5.6.20 Batch Entity Merge +
+none +
+Temporal Context Consumer +
+In case of direct interactions with Context Registry: +
+
+5.11.7 CSR Notification - if supporting asynchronous +interactions +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
+
+ +
+
+In case of direct interactions with Context Registry: +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+ +
+
+if supporting asynchronous interactions: +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+Temporal Context Producer +
+None +
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
+Temporal Context Source +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+
+5.7.4 Query Temporal Evolution of Entities +
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+Temporal Context Repository +
+5.6.11 Upsert Temporal Evolution of an Entity +
+
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+
+5.6.14 Partial Update Attribute instance +
+
+5.6.15 Delete Attribute Instance +
+
+5.6.16 Delete Temporal Evolution of an Entity +
+none +
+Context Registry +
+5.9.2 Register Context Source +
+
+5.9.3 Update CSR +
+
+5.9.4 Delete CSR +
+
+5.7.1 Retrieve CSR +
+
+5.7.2 Query CSRs +
+
+5.11.2 Create CSR Subscription +
+
+5.11.3 Update CSR Subscription +
+
+5.11.4 Retrieve CSR Subscription +
+
+5.11.5 Query CSR Subscription +
+
+5.11.6 Delete CSR Subscription +
+5.11.7 CSR Notification +
+

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 +and 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 relates +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 redirect Context Source +Registration also specifies that the registered context data is +held in a location external to the Context +Broker. It is possible to register (any combination of): +
+
    +
  • +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 +[27])) 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

+
+If the optional array (of KeyValuePair type, as defined by clause +5.2.22) contextSourceInfo of the CSourceRegistration is +present, it contains, whatever extra information the Context Broker shall convey when contacting +the Context Source. This can be +information the Context Broker needs +to successfully communicate with the Context +Source (e.g. Authorization material), or for the Context Source to correctly interpret the +received content (e.g. the Link URL to fetch an @context). The +method for conveying this information is binding-specific, e.g. using +headers in the case of HTTP. +
+
+Instead of providing the actual value, the special value "urn:ngsi-ld:request" can be used to indicate +that the respective value is to be taken from the request that triggered +the given request, if present. +
+
+
+EXAMPLE: +
+
+If + +the + +key + +value + +pair + +"user": + +"urn:ngsi-ld:request" +is + +part + +of + +contextSourceInfo + +of + +the + +CSourceRegistration, + +the + +Context Broker + +checks + +if + +"user" + +was + +conveyed + +in + +the + +triggering + +request. + +If + +this + +is + +the + +case, + +e.g. + +"user": + +"abcd" +, + +"user": + +"abcd" + +is + +also + +conveyed + +when + +contacting + +the + +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

+
+The following key-values have a specific well-defined meaning when +defined as elements within the optional array contextSourceInfo +of the CSourceRegistration. +
+
+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. +
    +
    +If the key "contentType" is defined: +
    • +
  • +the value shall be a MIME type acceptable to the Context Broker (one of: +"application/json", "application/ld+json"). +
    • +
  • +the Context Broker shall provide the request and the associated +@context as required by the MIME type when distributing the +request to the context source endpoint, regardless of how it was +provided in the initial request. +
    +
    +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 "ngsildConformance" is defined: +
    • +
  • +the value shall defined in the form major.minor, for example 1.5. +
    • +
  • +the Context Broker shall apply a backwards compatibility operation over +the payload (as defined by clause +4.3.6.8) prior to distributing the request to the context source +endpoint such that the forwarded payload conforms to the specified +version of the NGSI-LD specification +
    • +
+

4.3.6.7 Querying +and Retrieving 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 process each Context Consumption request +efficiently, and to support consistent pagination, it is necessary for +the Context Broker to initially make +a broad request to each registered Context +Source whose registration is matching the request.

+

In the case of a query Entities +operation (clause +5.7.2) or query Temporal Evolution of Entities +operation (clause +5.7.4), a list of Entity identifiers is returned and stored together +with the registration information in an Entity map. Only the Entities +whose identifiers are contained in the Entity map are considered when +rendering the result pages. Filtering based on queries, geoqueries, +scope queries or attribute filters, as provided in the original query +request, is applied to the Entities before adding the Entity to a result +page, i.e. identifiers of Entities not matching the filters at the time +of checking are removed from the Entity map.

+

In the case of a retrieve Entity +operation (clause +5.7.1) or retrieve Temporal Evolution of an Entity +operation (clause +5.7.3), an Entity map can be used to make subsequent retrievals of +the same Entity more efficient, as the Entity map provides the +information about which Context Source(s) store relevant Entity +information, and other Context Sources do not have to be considered.

+

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 Table 6.4.3.2‑2) +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.

+

When executing Context Consumption or +Subscription operations, a significant optimization in +performance can be achieved if it is known a priori whether individual +Entities are themselves distributed among Context Brokers and Context +Sources, or if each Context Broker and Context Source always stores +complete Entities. In the latter case all parameters used for filtering +such as queries, geoqueries, scope queries or attribute filters can be +forwarded and applied locally, whereas in the former case, the Entity +first has to be assembled by the Context Broker and only then the +filtering can be applied. Since being able to apply filters locally is +significantly more efficient, a parameter can indicate that, for the +given request, only Entities are to be expected that are stored in their +entirety on each Context Broker and each Context Sources, and there are +no Entities that are themselves stored in a distributed fashion. Such +Entities are also referred to as split Entities. Context Broker +implementations should enable configuring a default for this parameter, +so deployments where no split Entities are to be expected can filter +locally and thus be more efficient.

+

In the case of split Entities, EntityMaps initially only store +“candidate Entities” as no filters could be applied, because only a part +of the Entity was available. In the process of pagination, the filters +will be (re-)checked. Any Entity not (or no longer) fulfilling the +filter shall be removed from the EntityMap.

+

4.3.6.8 +Backwards compatibility of Context Source payloads

+

When retrieving Entity data found distributed across multiple +associated Context Brokers each Context Source is sent a context +consumption request. A Context Broker shall assume that every +Context Source will return valid NGSI-LD Entity data in a format that it +understands and it shall reject data that is invalid. However, since the +definition of a valid NGSI-LD Entity has broadened with each version of +the NGSI-LD specification, it is possible that a registered Context +Source could respond with valid NGSI-LD Entity data which does not fit +the narrower confines of a previous NGSI-LD specification.

+

Therefore when making a context consumption request, +a Context Broker may wish to indicate that it is only capable of +interpreting responses which conform to a specific NGSI-LD +specification, in which case the Context Source shall endeavour to amend +its payload accordingly. Table 4.3.6.7‑1 +describes a minimal level of support for a NGSI-LD Entity data as +specified by each version of the NGSI-LD specification, and the expected +fallback behaviour required if a context consumption +request is made to receive data conformant to an earlier version of the +NGSI-LD specification. Table 4.3.6.7‑2 +describes conformance fallbacks for an NGSI-LD Property (and its +subclasses) and Table 4.3.6.7‑2 describes +conformance fallbacks for an NGSI-LD Relationship (and its +subclasses).

+

The version of the NGSI-LD specification requested and the conformant +version returned is defined in the form major.minor, for example +1.5.

+
+Table 4.3.6.8-1: NGSI-LD Entity data type attribute support +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Definition +
+Version +
+
+Introduced +
+Conformant
+Data Fallback +
+id +
+String +
+Valid URI +
+1.0 +
+ +
+type +
+String or String[]1 +
+ +
+1.0 +
+ +
+location +
+GeoProperty +
+Default geospatial Property of an entity. See clause +4.7 +
+1.0 +
+ +
+observationSpace +
+GeoProperty +
+See clause +4.7 +
+1.0 +
+ +
+operationSpace +
+GeoProperty +
+See clause +4.7 +
+1.0 +
+ +
+scope +
+String or String[] +
+See clause +4.18 +
+1.4 +
+Remove attribute from payload +
+expiresAt +
+String +
+DateTime as mandated by clause +4.22 +
+1.9 +
+Remove attribute from payload +
+<Property name> +
+
+ +
+Property +
+
+or Property[]2 +
+Property as mandated by clause +4.5.2. +
+1.0 +
+ +
+GeoProperty or GeoProperty[]2 +
+GeoProperty as mandated by clause +4.5.2. +
+1.0 +
+ +
+LanguageProperty or LanguageProperty[]2 +
+LanguageProperty as mandated by clause +4.5.18. +
+1.4 +
+Reformat attribute as Property +
+JsonProperty or JsonProperty[]2 +
+JsonProperty as mandated by clause +4.5.24. +
+1.8 +
+Reformat attribute as Property +
+VocabProperty or VocabProperty[]2 +
+VocabProperty as mandated by clause +4.5.20. +
+1.8 +
+Reformat attribute as Property +
+ListProperty or ListProperty[]1 +
+ListProperty as mandated by clause +4.5.21. +
+1.8 +
+Reformat attribute as Property +
+<Relationship name> +
+
+ +
+Relationship +
+
+or Relationship[]3 +
+Relationship as mandated by clause +4.5.3. +
+1.0 +
+ +
+ListRelationship or ListRelationship[]3 +
+ListRelationship as mandated by clause +4.5.22. +
+1.8 +
+Reformat attribute as Relationship +
+
+NOTE 1: +
+
+1: + +From + +1.3 + +onwards, + +an + +Entity + +type + +can + +be + +assigned + +multiple + +values + +For + +1.0 + +backwards + +compatibility + +only + +return + +a + +single + +element + +with + +preference + +to + +the + +first + +instance. +
+
+
+
+NOTE 2: +
+
+2: + +From + +1.3 + +onwards, + +multiple + +instances + +of + +a + +Property + +(or + +subclass + +of + +Property +) + +identified + +by + +the + +same + +Property + +name + +can + +be + +separated + +by + +datasetId. + +For + +1.0 + +backwards + +compatibility + +only + +return + +a + +single + +element + +of + +Property + +Array + +with + +preference + +to + +the + +default + +instance. +
+
+
+
+NOTE 3: +
+
+3: + +From + +1.3 + +onwards, + +multiple + +instances + +of + +a + +Relationship + +(or + +subclass + +of + +Relationship +) + +identified + +by + +the + +same + +Relationship + +name + +can + +be + +separated + +by + +datasetId. + +From + +1.3 + +onwards. + +For + +1.0 + +backwards + +compatibility + +only + +return + +a + +single + +element + +of + +Relationship + +Array + +with + +preference + +to + +the + +default + +instance. +
+
+
+Table 4.3.6.8-2: NGSI-LD Property data type attribute support +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Definition +
+Version
+Introduced +
+Conformant
+Data Fallback +
+type +
+String +
+ +
+1.0 +
+ +
+value +
+Any JSON value as defined by IETF RFC 8259 [6] +
+See NGSI-LD Value definition in clause +3.1 +
+1.0 +
+ +
+datasetId +
+String +
+Valid URI as mandated by clause +4.5.5 +
+1.3 +
+Remove attribute from payload +
+expiresAt +
+String +
+DateTime as mandated by clause +4.22 +
+1.9 +
+Remove atrribute from payload +
+observedAt +
+String +
+DateTime as mandated by clause +4.8 +
+1.3 +
+Remove attribute from payload +
+unitCode +
+String +
+As mandated by [15] +
+1.3 +
+Remove attribute from payload +
+valueType +
+String +
+See clause 4.5.2 +
+1.9 +
+Remove attribute from payload +
+
+Table 4.3.6.8-3: NGSI-LD Relationship data type attribute support +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Name +
+Data Type +
+Definition +
+Version
+Introduced +
+Conformant
+Data Fallback +
+type +
+String +
+Valid URI +
+1.0 +
+ +
+object +
+String or String[] +
+ +
+1.0 +
+ +
+datasetId +
+String +
+Valid URI as mandated by clause +4.5.5 +
+1.3 +
+Remove attribute from payload +
+expiresAt +
+String +
+DateTime as mandated by clause +4.22 +
+1.9 +
+Remove attribute from payload +
+objectType +
+String or String[] +
+See clause +4.5.23 +
+1.8 +
+Remove attribute from payload +
+observedAt +
+String +
+DateTime as mandated by clause +4.8 +
+1.3 +
+Remove attribute from payload +
+

When responding to a context consumption request to +supply data conforming to a specific NGSI-LD specification, Context +Sources should indicate the version of the specification the returned +payload actually conforms to. In +general, Context Sources will not be expected to be flexibile enough to +supply payloads conformant to all past and future versions of the +specification, but the requesting Context Broker may use supplied +version information when collating data from multiple Context Sources. +and to validate and amend received payloads.

+

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

+
    +
  • +"expiresAt": a string as mandated by clause +4.22. +
    • +
  • +"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. +
    • +
+
+
+NOTE 1: +
+
+In + +the + +following, + +the + +term + +Attribute + +is + +used + +when + +referring + +in + +the + +text + +to + +both + +a + +Property + +and + +a + +Relationship + +(see + +definition + +of + +NGSI-LD + +Attribute + +in + +clause +3.1 +). +
+
+
+
+NOTE 2: +
+
+When + +GeoJSON + +representation + +is + +selected, + +the + +layout + +of + +the + +Entities + +changes, + +see + +clause +4.5.16 + +for + +details. +
+
+

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. +
    • +
  • +"expiresAt": a string as mandated by clause +4.22. +
    • +
  • +"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]. +
    • +
  • +"valueType": a string value which shall be type coerced into a datatype +URI. It is a non-reified alternative to the use of a native JSON-LD +@type for the Property value. When it is a JSON primitive, it +should align this with the RDF datatype [34]. +
    • +
  • +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. +
    • +
  • +"expiresAt": a string as mandated by clause +4.22. +
    • +
  • +"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]. +
    • +
  • +"valueType": a string value which shall be type coerced into a datatype +URI. It is a non-reified alternative to the use of a native JSON-LD +@type for the Property value. When it is a JSON primitive, it +should align this with the RDF datatype [34]. +
    • +
  • +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. +
    • +
  • +"expiresAt": a string as mandated by clause +4.22. +
    • +
  • +"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. +
    • +
  • +"expiresAt": a string as mandated by clause +4.22. +
    • +
  • +"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. +
    • +
+
+
+EXAMPLE 1: +
+
+ +"name": "David Robert Jones" +
+
+
    +
  • +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 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". +
    • +
+
+
+EXAMPLE 2: +
+
+2: +
+
+
+
+"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: +
+
+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: +
+
+ +" +provi +d +edBy +": "urn:ngsi-ld: +Device +:31415 +" +
+
+
+
+EXAMPLE 8: +
+
+8: +
+
+
+"devices": [ +
+
+     "urn:ngsi-ld:Device:14142", +
+
+     "urn:ngsi-ld:Device:13562",  +
+
+     "urn:ngsi-ld:Device:37309" +
+
+] +
+
+ +
+
    +
  • +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: +
+
+9: +
+
+
+"providedBy": { +
+
+  "id": "urn:ngsi-ld:Device:31415", +
+
+  "type": "Device", +
+
+  "brandName": "Anemometer", +
+
+  "manufacturerName": "Cyberdyne Systems", +
+
+  "windSpeed": 60 +
+
+}
+ +
+
+
+EXAMPLE 10: +
+
+10: +
+
+
+"devices": [ +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:14142", +
+
+       "type": "Device", +
+
+       "brandName": "Anemometer", +
+
+       "manufacturerName": "Cyberdyne Systems", +
+
+        "windSpeed": 60 +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:13562", +
+
+       "type": "Device", +
+
+       "brandName": "Hygromometer", +
+
+       "manufacturerName": "Acme Corporation", +
+
+       "humidity": 64 +
+
+    }, +
+
+    {  +
+
+       "id": "urn:ngsi-ld:Device:37309", +
+
+       "type": "Device", +
+
+       "brandName": "Barometer", +
+
+       "manufacturerName": "Trask Industries", +
+
+       "pressure": 760 +
+
+    } +
+
+] +
+
    +
  • +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: +
+
+11: +
+
+
+[ +
+
+  { +
+
+    …etc +
+
+    "providedBy": "urn:ngsi-ld:Device:31415" +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:Device:31415", +
+
+    "type": "Device", +
+
+    "brandName": "Anemometer", +
+
+    "manufacturerName": "Cyberdyne Systems", +
+
+    "windSpeed": 60 +
+
+  } +
+
+]
+ +
+
+
+EXAMPLE 12: +
+
+12: +
+
+
+[ +
+
+    { +
+
+      … etc +
+
+      "providedBy": [ +
+
+       "urn:ngsi-ld:Device:14142",  +
+
+         "urn:ngsi-ld:Device:13562",  +
+
+         "urn:ngsi-ld:Device:37309" +
+
+       ] +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:14142", +
+
+       "type": "Device", +
+
+       "brandName": "Anemometer", +
+
+       "manufacturerName": "Cyberdyne Systems", +
+
+       "windSpeed": 60 +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:13562", +
+
+       "type": "Device", +
+
+       "brandName": "Hygromometer", +
+
+       "manufacturerName": "Acme Corporation", +
+
+       "humidity": 64 +
+
+    }, +
+
+    { +
+
+       "id": "urn:ngsi-ld:Device:37309", +
+
+       "type": "Device", +
+
+       "brandName": "Barometer", +
+
+       "manufacturerName": "Trask Industries", +
+
+       "pressure": 760 +
+
+    } +
+
+] +
+
+ +
+
    +
  • +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 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: +
+
+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. +
    • +
+
+
+EXAMPLE 14: +
+
+ +"periods": ["First", "Second", "Third", "Fourth"] +
+
+
    +
  • +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 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: +
+
+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). +
    • +
+
+
+EXAMPLE 16: +
+
+16: +
+
+
+"route":[ +
+
+  "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. +
    • +
+
+
+EXAMPLE 17: +
+
+17: +
+
+
+"route": [ +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0101", +
+
+    "type": "BusStop", +
+
+    "stopName": "High Street", +
+
+    "location": {"type": Point, coordinates [54.112,0.334]}} +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0102", +
+
+    "type": "BusStop", +
+
+    "stopName": "Station Road",  +
+
+    "location": {"type": Point, coordinates [54.101,0.302]}} +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:9912", +
+
+    "type": "BusStop", +
+
+    "stopName": "Mornington Cresent",  +
+
+    "location": {"type": Point, coordinates [54.142,0.332]} +
+
+  } +
+
+] +
+
+ +
+
+ +
+
    +
  • +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. +
    • +
+
+
+EXAMPLE 18: +
+
+18: +
+
+
+[ +
+
+  { +
+
+    …etc +
+
+    "route": [ +
+
+      "urn:ngsi-ld:BusStop:0101", +
+
+      "urn:ngsi-ld:BusStop:0102", +
+
+      "urn:ngsi-ld:BusStop:9912" +
+
+    ] +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0101" +
+
+    "type": "BusStop", +
+
+    "stopName": "High Street",  +
+
+    "location: {"type": "Point", "coordinates": [54.112,0.334]}} +
+
+  { +
+
+    "id": "urn:ngsi-ld: BusStop:0102", +
+
+    "type": "BusStop", +
+
+    "stopName": "Station Road",  +
+
+    "location": {"type": "Point", "coordinates": [54.101,0.302]}} +
+
+  }, +
+
+  { +
+
+    "id": "urn:ngsi-ld:BusStop:9912" +
+
+    "type": "BusStop", +
+
+    "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 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: +
+
+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" +
+
+    ] +
+
+  } +
+
+} +
+
+
+ +
+
+
+
+NOTE: +
+
+When + +the + +simplified + +GeoJSON + +representation + +is + +selected, + +the + +layout + +of + +the + +Entities + +changes, + +see + +clause +4.5.17 + +for + +details. +
+
+

4.5.5 Multi-Attribute Support

+

4.5.5.1 Introduction

+

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, expiresAt and observedAt, +and also the unitCode Property.

+

4.5.5.2 Processing of +Conflicting Transient Entities

+

In case of conflicting information when an Entity is received from a +registered Context Source and marked with an expiresAt DateTime, +but this expiresAt is not duplicated across all versions of the +Entity received across all registered Context Sources, the following +mechanism shall be used to differenciate:

+

For each version of the Entity received where the expiresAt +non-reified attribute is present at the Entity level:

+
    +

  • If no expiresAt attribute is present as a property of an +Attribute, a non-reified expiresAt attribute is added as a +property of that Attribute corresponding to to the expiresAt +found on the Entity.

    • +

  • If the expiresAt attribute is present as a property of an +Attribute, and the value on the Attribute is further in the future than +the expiresAt value found on the Entity, the value of the +expiresAt on the Attribute is overwritten to corresponding to the +earlier DateTime.

    • +
+

4.5.5.3 Processing of +Conflicting Attributes

+

In case of conflicting information for an Attribute, where a +datasetId is duplicated, but there are differences in the other +attribute data, if an expiresAt DateTime is present on the +Attribute and the date lies in the past, it shall be discarded, +thereafter 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.

+

When conflicting information is received for the non-reified +expiresAt attribute at an Entity level:

+
    +

  • If an expiresAt attribute is missing from at least one +version of the Entity received from registered Context Sources, the +expiresAt attribute is removed from the Entity.

    • +

  • Otherwise the expiresAt attribute of the Entity is set to +the DateTime corresponding to the expiresAt +DateTime which is furthest in the future.

    • +
+

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 a 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: +
+
+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: +
+
+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: +
+
+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: +
+
+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: +
+
+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: +
+
+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" +
+
+    ] +
+
+  ] +
+
+} +
+
+
+
+EXAMPLE 7: +
+
+7: +
+
+
+
+"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: +
+
+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:

+
+Prohibited +
+
    +
  • +"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:

+

Prohibited

+
    +
  • +"unitCode": shall never be present, as +language maps are always strings and hence unitless. +
    • +
  • +"value" and "previousValue": 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: +
    • +
+
+1) the value obtained after applying the aggregation method over the +period; +
+
+2) the start DateTime of the corresponding period; +
+
+3) the end DateTime of the corresponding period. +
+
    +
  • +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: +
    • +
+
+1) the value obtained after applying the aggregation method over the +period; +
+
+2) the start DateTime of the corresponding period; +
+
+3) the end DateTime of the corresponding period. +
+

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:

+
+Table 4.5.19.1-1: Semantics of aggregation methods for Properties on +JSON native data types +
+ ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+JSON String +
+JSON Number +
+JSON Object +
+JSON Array +
+JSON Boolean +
+
+(see note) +
+totalCount +
+Calculate the number of times the value has been updated inside the +period +
+distinctCount +
+Calculate the count of distinct values inside the period +
+sum +
+N/A +
+Calculate the sum of the values inside the period +
+N/A +
+Calculate the sum of the sizes of the arrays inside the period +
+Calculate the sum of the values inside the period +
+avg +
+N/A +
+Calculate the average of the values inside the period +
+N/A +
+Calculate the average number of the sizes of the arrays inside the +period +
+Calculate the average of the values inside the period +
+min +
+Calculate the first value in lexicographical order inside the period +
+Calculate the minimum value inside the period +
+N/A +
+Calculate the minimum size of the arrays inside the period +
+Calculate the minimum value inside the period +
+max +
+Calculate the last value in lexicographical order inside the period +
+Calculate the maximum value inside the period +
+N/A +
+Calculate the maximum size of the arrays inside the period +
+Calculate the maximum value inside the period +
+stddev +
+N/A +
+Calculate the standard deviation of the values inside the period +
+N/A +
+N/A +
+Calculate the standard deviation of the values inside the period +
+sumsq +
+N/A +
+Calculate the sum of the square of the values inside the period +
+N/A +
+N/A +
+Calculate the sum of the square of the values inside the period +
+
+NOTE: +
+
+For + +the + +purpose + +of + +aggregation, + +true +is + +considered + +as + +a + +value + +of + +1, + +false + +is + +considered + +as + +a + +value + +of + +0. +
+
+
+Table 4.5.19.1-2: Semantics of aggregation methods for Properties on +other supported data types +
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+DateTime +
+Date +
+Time +
+URI +
+totalCount +
+Calculate the number of times the value has been updated inside the +period +
+distinctCount +
+Calculate the count of distinct values inside the period +
+sum +
+N/A +
+N/A +
+N/A +
+N/A +
+avg +
+N/A +
+N/A +
+Calculate the average time inside the period (e.g. to apply on an event +that occurs at non fixed times, like the time a car enters a given +parking) +
+N/A +
+min +
+Calculate the minimum value inside the period +
+Calculate the minimum value inside the period +
+Calculate the minimum value inside the period +
+N/A +
+max +
+Calculate the maximum value inside the period +
+Calculate the maximum value inside the period +
+Calculate the maximum value inside the period +
+N/A +
+stddev +
+N/A +
+N/A +
+N/A +
+N/A +
+sumsq +
+N/A +
+N/A +
+N/A +
+N/A +
+
+Table 4.5.19.1-3: Semantics of aggregation methods for Relationships +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Aggregation Method +
+Relationship +
+totalCount +
+Calculate the number of times the relationship has been updated inside +the period +
+distinctCount +
+Calculate the count of distinct relationships targets inside the period +
+sum +
+N/A +
+avg +
+N/A +
+min +
+N/A +
+max +
+N/A +
+stddev +
+N/A +
+sumsq +
+N/A +
+

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:

+

Prohibited

+
    +
  • +"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:

+

Prohibited

+
    +
  • +"unitCode": shall never be present, as +vocabs are always strings and hence unitless. +
    • +
  • +"value" and "previousValue": 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 clause +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:

+

Prohibited

+
    +
  • +"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 clause +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:

+
+Prohibited +
+
    +
  • +"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:

+

Prohibited

+
    +
  • +"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:

+

Prohibited

+
    +
  • +"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.

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

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:

+

Prohibited

+
    +
  • +"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:

+

Prohibited

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

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:

+
+nameChar = unicodeNumber / unicodeLetter +
+
+nameChar =/ %x5F          ; _ +
+
+name = unicodeLetter *nameChar +
+
+ +
+
    +
  • +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:

+
+prefix = unicodeLetter *nameChar +
+
+name =/ prefix %x3A unicodeLetter *nameChar ; prefix:name +
+
+ +
+

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. +
    • +
+
+
+NOTE 1: +
+
+In + +previous + +versions + +of + +NGSI-LD, + +only + +the + +comma + +was + +supported + +as + +ISO + +8601 + +[17] + +states + +that + +it + +is + +the + +preferred + +option. + +However, + +in + +practice + +the + +decimal + +point + +is + +more + +commonly + +used +. +
+
+
    +
  • +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. +
    • +
+
+
+NOTE 2: +
+
+In + +previous + +versions + +of + +NGSI-LD, + +only + +the + +comma + +was + +supported + +as + +ISO + +8601 + +[17] + +states + +that + +it + +is + +the + +preferred + +option. + +However, + +in + +practice + +the + +decimal + +point + +is + +more + +commonly + +used. +
+
+
    +
  • +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. +
    • +
  • +expiresAt is defined as the temporal Property at which +the Entity, Property or Relationship should be 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.

+
+
+NOTE 1: +
+
+For + +simplicity + +reasons, + +a + +TemporalProperty + +is + +represented + +only + +by + +its + +Value, + +i.e. + +no + +Properties + +of + +TemporalProperty + +nor + +Relationships + +of + +TemporalProperty + +can + +be + +conveyed. + +In + +more + +formal + +language, + +a + +TemporalProperty + +does + +not + +allow + +reification. +
+
+
+
+NOTE 2: +
+
+It + +is + +important + +to + +remark + +that + +the + +term + +TemporalProperty + +has + +been + +reserved + +for + +the + +semantic + +tagging + +of + +non-reified + +structural + +timestamps + +( +observedAt +, + +createdAt +, + +modifiedAt, deletedAt +, + +expiresAt +), + +which + +capture + +the + +temporal + +evolution + +of + +Attributes. + +Only such structural timestamps can be used as + +timeproperty + +in Temporal Queries as mandated by clause +4.11 +. +
+
+
+
+NOTE 3: +
+
+User-defined + +Properties + +whose + +value + +is + +a + +time + +value + +( +Date, DateTime or Time +) + +are + +defined + +as + +Property +, + +not + +as + +TemporalProperty +, + +and + +are + +serialized + +in + +NGSI-LD + +as + +shown + +in + +annex + +C, + +clause +C.6 +. +
+
+

Whenever a TemporalProperty value is unknown by a registered +Context Source, the Property shall be +omitted rather than sending an error response.

+

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:

+
+Query = (QueryTerm / QueryTermAssoc) *(LogicalOp (QueryTerm / +QueryTermAssoc)) +
+
+QueryTermAssoc = %x28 QueryTerm *(LogicalOp QueryTerm) %x29 ; +(QueryTerm) +
+
+QueryTerm = Attribute +
+
+QueryTerm =/ Attribute Operator ComparableValue +
+
+QueryTerm =/ Attribute equal CompEqualityValue +
+
+QueryTerm =/ Attribute unequal CompEqualityValue +
+
+QueryTerm =/ Attribute patternOp RegExp +
+
+QueryTerm =/ Attribute notPatternOp RegExp +
+
+Attribute = LinkedEntityRelation +
+
+LinkedEntityRelation = AttrName %x7B LinkedEntityPath %x7D ; +AttrName{LinkedEntityPath} +
+
+LinkedEntityRelation =/ ValuePath +
+
+LinkedEntityPath = *1(EntityType 1*(%x2C EntityType) %x3A) AttrName %x7B +LinkedEntityPath %x7D +
+
+;*1(EntityType 1*(,EntityType):)AttrName{LinkedEntityPath} +
+
+LinkedEntityPath =/ ValuePath +
+
+ValuePath = DottedPath *1(%x5B DottedPath %x5D) ; DottedPath +*1([DottedPath]) +
+
+DottedPath = AttrName *(%x2E AttrName) ; AttrName *(.AttrName) +
+
+Operator = equal / unequal / greaterEq / greater / lessEq / less +
+
+ComparableValue = Number / quotedStr / dateTime / date / time +
+
+OtherValue = false / true +
+
+Value = ComparableValue / OtherValue +
+
+Range = ComparableValue dots ComparableValue +
+
+ValueList = Value 1*(%x2C Value) ; Value 1*(, Value) +
+
+CompEqualityValue = OtherValue / ValueList / Range / URI +
+
+equal = %x3D %x3D ; == +
+
+unequal = %x21 %x3D ; != +
+
+greater = %x3E ; > +
+
+greaterEq = %x3E %x3D ; >= +
+
+less = %x3C ; < +
+
+lessEq = %x3C %x3D ; <= +
+
+patternOp = %x7E %x3D ; ~= +
+
+notPatternOp = %x21 %x7E %x3D ; !~= +
+
+dots = %x2E %x2E ; .. +
+
+TermChar = unicodeNumber / unicodeLetter +
+
+TermChar =/ %x5F ; _ +
+
+AttrName = unicodeLetter *TermChar +
+
+EntityType = unicodeLetter *TermChar +
+
+quotedStr = String ; "*char" +
+
+andOp = %x3B ; ; +
+
+orOp = %x7C ; | +
+
+LogicalOp = andOp / orOp +
+
+ +
+
    +
  • +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.

+
+
+EXAMPLE 0: +
+
+ +?q= +temperature +. + +(checks + +for + +the + +existence + +of + +the + +attribute + +temperature) +
+
+
+
+EXAMPLE 1: +
+
+ +?q= +temperature==20 +
+
+
+
+EXAMPLE 2: +
+
+ +?q= +brandName!="Mercedes" +
+
+
+
+EXAMPLE 3: +
+
+ +?q= +isParked=="urn:ngsi-ld:OffStreetParking:Downtown1" +
+
+
+
+EXAMPLE 4: +
+
+A + +query + +encoded + +as + +an + +HTTP + +Query + +String. + +Note + +that + +this + +is + +HTTP + +binding + +specific, + +to + +be + +used + +via + +GET + +method, + +as + +defined + +in + +clause 6.4.3.2 +. + +The + +NGSI-LD + +query + +language + +string + +is + +conveyed + +by + +means + +of + +parameter + +q. +
+
+
+
+ +
+
+ +
+
+
+
+EXAMPLE 5: +
+
+ +?q= +isMonitoredBy + +(to + +query + +Entities + +that + +have + +the + +Attribute + +isMonitoredBy +) +
+
+

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.

+
+
+EXAMPLE 6: +
+
+ +?q= +((speed>50|rpm>3000);brandName=="Mercedes") +
+
+
+
+EXAMPLE 7: +
+
+ +?q= +(temperature>=20;temperature<=25)|capacity<=10 +
+
+

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. +
    • +
+
+
+EXAMPLE 8: +
+
+ +?q= +temperature.observedAt>=2017-12-24T12:00:00Z +
+
+

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.

+
+
+EXAMPLE 9: +
+
+ +?q= +address[city]=="Berlin" +. + +The + +trailing + +path + +is + +[city] +. + +It + +is + +used + +to + +refer + +to + +a + +particular + +subitem + +within + +the + +value + +of + +the + +address + +Property +, + +which + +is + +a + +complex + +JSON + +object + +representing + +a + +postal + +address. + +Refer + +to + +the + +following + +NGSI-LD + +Entity: +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:placedescription:123", +
+
+  "type": "PlaceDescription", +
+
+  "address": { +
+
+    "type": "Property", +
+
+    "value": { +
+
+      "city": "Berlin", +
+
+      "street": "Ulrich Strasse" +
+
+    } +
+
+  } +
+
+} +
+
+
+ +
+
+
+
+EXAMPLE 10: +
+
+ +?q= +sensor.rawdata[airquality.particulate]==40 +. + +The + +trailing + +path + +is + +[airquality.particulate]. + +The + +particulate Property + +of + +the + +compound + +JSON + +object + +is + +targeted. + +Refer + +to + +the + +following + +NGSI-LD + +Entity: +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:particulatemeasurement:345", +
+
+  "type": "ParticulateMeasurement", +
+
+  "sensor": { +
+
+    "type": "Property", +
+
+    "value": 40, +
+
+    "rawdata": { +
+
+      "type": "Property", +
+
+      "value": { +
+
+        "airquality": { +
+
+          "particulate": 40, +
+
+          "PM20": 85 +
+
+        } +
+
+      } +
+
+    } +
+
+  } +
+
+} +
+
+ +
+
+
+EXAMPLE 11: +
+
+ +?q=parkingTickets[value]== +" +Overstay 60 minutes +" +& +jsonKeys=parkingTickets +. + +The + +trailing + +path + +is + +parkingTickets +. + +The + +parkingTickets +Property + +of + +the + +JSON + +object + +is + +targeted, + +but + +the + +target + +value + +raw + +is + +JSON, + +and + +is + +not + +expanded + +to + +ngsi-ld:hasValue + +using + +the + +core + +@context +. + +Refer + +to + +the + +following + +NGSI-LD + +Entity: +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:Car:6152s", +
+
+  "type": "Car", +
+
+  "parkingTickets": { +
+
+  "type": "JsonProperty", +
+
+  "json": { +
+
+         "id": "85a6cc52-0589-45f9", +
+
+         "value": "Overstay 60 minutes" +
+
+      } +
+
+  } +
+
+} +
+
+ +
+
+
+EXAMPLE 12: +
+
+ +?q=gender==Male& +expandValues=gender +. + +The + +trailing + +path + +is + +gender +. + +The + +gender + +Property + +of + +JSON + +object + +is + +targeted, + +but + +the + +target + +value + +is + +first + +expanded + +to + +a + +URI + +using + +the + +supplied + +@context +. + +Refer + +to + +the + +following + +NGSI-LD + +Entity: +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:Person:678", +
+
+  "type": "Person", +
+
+  "gender": { +
+
+    "type": "VocabProperty", +
+
+    "vocab": "Male", +
+
+    } +
+
+  }, +
+
+  @context": { +
+
+    "Male": "http://example.org/Male", +
+
+  } +
+
+} +
+

The filter can also apply to a Property or Relationship +of an NGSI-LD Entity targeted by a (recursively) followed +Relationship, for example as part of a linked entity retrieval (clause +4.5.23).

+
+
+EXAMPLE 13: +
+
+ +?q=sensor{humidity}==40 +. + +The + +trailing + +path + +is + +sensor +{humidity} +. + +The + +query + +targets + +entities + +with + +a + +sensor + +Relationship + +and + +makes + +a + +sub-query + +on + +matching + +target + +objects + +which + +have + +the + +matching + +humidity + +Attribute. + +Refer + +to + +the + +following + +NGSI-LD + +Entities: +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:WeatherStation:123", +
+
+  "type": "WeatherStation", +
+
+  "sensor": { +
+
+    "type": "Relationship", +
+
+  "objectType": "Device", +
+
+    "object": "urn:ngsi-ld:Device:345" +
+
+  } +
+
+} +
+
+ +
+
+{ +
+
+  "id": "urn:ngsi-ld:Device:345", +
+
+  "type": "Device", +
+
+  "humidity": { +
+
+    "type": "Property", +
+
+    "value": 40 +
+
+  } +
+
+} +
+
+ +
+

As not knowing the Entity Type targeted by a Relationship +could make the query significantly more expensive, a hint for the +required Entity Type can be provided, so only such NGSI-LD Entities need +to be considered.

+
+
+EXAMPLE 14: +
+
+ +?q=sensor{Device:humidity}==40 +. + +The + +trailing + +path + +is + +sensor +{Device:humidity} +. + +The + +query + +targets + +entities + +with + +a + +sensor +. +entityType = +" +Device" + +within + +a + +Relationship + +and + +then + +makes + +a + +sub-query + +on + +matching + +target + +objects + +which + +have + +the + +matching + +humidity + +Attribute. + +The + +entityType + +hint + +results + +in + +a + +faster + +lookup. + +Refer + +to + +the + +following + +NGSI-LD + +Entities. +
+
+
+{ +
+
+  "id": "urn:ngsi-ld:WeatherStation:123", +
+
+  "type": "WeatherStation", +
+
+  "sensor": { +
+
+    "type": "Relationship", +
+
+  "objectType": "Device", +
+
+    "object": "urn:ngsi-ld:Device:345" +
+
+  } +
+
+} +
+
+ +
+
+{ +
+
+  "id": "urn:ngsi-ld:Device:345", +
+
+  "type": "Device", +
+
+  "humidity": { +
+
+    "type": "Property", +
+
+    "value": 40 +
+
+  } +
+
+} +
+
+ +
+

If the target element corresponds to a Relationship or +ListRelationship, the combination of such target element with any +operator different than equal or unequal shall result in +not matching.

+

A Query Term value shall be any of the following +(depending on the operator used):

+
    +
  • +A literal value (string, number, date, etc.) (production rule named +Value). +
    • +
  • +A range of values (production rule named Range), specified +as a minimum and a maximum value. +
    • +
  • +A regular expression (production rule named RegExp). +
    • +
  • +A URI (production rule named URI). +
    • +
  • +A comma-separated list of literal values (production rule named ValueList). +
    • +
+

When comparing dates or times, the order relation considered shall be +a temporal one.

+

When it comes to comparing text strings, implementations:

+
    +
  • +shall follow the recommendations defined by IETF RFC 8259 [6], section 8.3. +
    • +
  • +should support the Unicode Collation Algorithm (UCA), as defined by +[13]. +
    • +
+

URI comparison should be performed so that the number of false +negatives is minimized, as recommended by IETF RFC 3986 [5], section 6.

+

The semantics of the different logical operators used by Query Terms +are described as follows and shall be supported by compliant +implementations:

+
    +
  • +Existence (only attribute is specified). A matching +entity shall contain the target element. +
    • +
  • +Equal operator (production rule named equal). A matching +Entity shall contain the target element and meet any of the following +conditions: +
    • +
+
    +
  • +The Query Term value, e.g. color=="red": +
    • +
+
    +
  • +Is identical or equivalent to the target value (e.g. matches "red"). +
    • +
  • +Is included in the target value, if the latter is an array (e.g. matches +["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a list of values (production rule named ValueList), e.g. +color=="black", "red": +
    • +
+
    +
  • +The target value is identical or equivalent to any of the list values +(e.g. matches "red"). +
    • +
  • +The target value includes any of the Query Term values, if the target +value is an array (e.g. matches ["red","blue"]). +
    • +
+
    +
  • +If the Query Term value is a range (production rule named Range), e.g. temperature==10..20: +
    • +
+
    +
  • +The target value is in the interval between the minimum and maximum of +the range (both included) (e.g. matches 15). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and a natural language is specified e.g. color[en]=="red": +
    • +
+
    +
  • +a match is found as the value of the key-value pair corresponding to the +specified natural language of the languageMap (e.g. matches {"fr": "rouge", "en": "red","de": "rot"} but +not {"fr": "red", "en": "black","de": +"blue"}). +
    • +
  • +a match is found as a single element from the array of values of the +key-value pair corresponding to the specified natural language of the +languageMap (e.g. matches {"fr": ["chat", +"rouge"], "en": ["red", "cat], "de": ["rote", "Katze"]} but not +{"fr": ["chat", "rouge"], "en" : ["coal", +"black"],"de": ["blaue", "Engel"]}). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and no natural language is specified e.g. color[*]=="red": +
    • +
+
    +
  • +any match is found in the values of the key-value pairs of the +languageMap (e.g. matches {"fr": "rouge", +"en": "red", "de": "rote"}. +
    • +
  • +a match is found as a single element of the array of values of the +key-value pairs of the languageMap (e.g. matches {"fr": "chat", "rouge"], "en": ["red", "cat"], "de": +["rote", "Katze"]}). +
    • +
+
    +
  • +The Query Term value is a URI and the target element corresponds to a +Relationship, a ListRelationship or a +VocabProperty, e.g. color=="http://example/red": +
    • +
+
    +
  • +Is identical to the target value (e.g. matches "http://example.com/red"). +
    • +
  • +Is included in the target value, if the latter is an array (e.g. matches +["http://example.com/blue"," +http://example.com/red"," http://example.com/green"]). +
    • +
+
    +
  • +If the Query Term value target element corresponds to a +Relationship, a ListRelationship or a VocabProperty and is a list of +URIs (production rule named ValueList), e.g. color==" +http://example/black","http://example/red": +
    • +
+
    +
  • +The target value is identical to any of the list values (e.g. matches +"http://example.com/red"). +
    • +
  • +The target value includes any of the Query Term values, if the target +value is an array (e.g. matches ["http://example.com/red", "http://example.com/blue"]). +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type, then it shall be considered as not matching. +
    • +
+
    +
  • +Unequal operator (production rule named unequal). A +matching entity shall contain the target element and meet any of the +following conditions: +
    • +
+
    +
  • +The Query Term value, e.g. color!="red": +
    • +
+
    +
  • +Is neither identical nor equivalent to the target value (e.g. matches +"black"). +
    • +
  • +Is not included in the target value, if the latter is an array (e.g. +matches ["blue","black","green"], +but not ["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a list of values (production rule named ValueList), e.g. +color!= "black", "red": +
    • +
+
    +
  • +The target value is neither identical nor equivalent to any of the list +values (e.g. matches "blue"). +
    • +
  • +The target value does not include any of the list values, if the target +value is an array (e.g. matches ["blue","yellow","green"], but not ["blue","red","green"]). +
    • +
+
    +
  • +If the Query Term value is a range (production rule named Range), e.g. temperature!=10..20: +
    • +
+
    +
  • +The target value is not in the interval between the minimum and the +maximum (both included) (e.g. matches 9). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and a natural language is specified e.g. color[en]!="red": +
    • +
+
    +
  • +No matching value is found as the value of the specified language key of +a languageMap where a language filter is specified. (e.g. matches +{"fr": "noir", "en": "black","de": +"schwarz"} but not {"fr": "rouge", "en" : +"red","de": "rot"}). +
    • +
  • +No matching value is found as a single element from the array of values +of the key-value pair corresponding to the specified natural language of +the languageMap (e.g. matches {"fr": +["chat", "rouge"], "en": ["coal", "black"], "de": ["blaue", +"Engel"]} but not {"fr": ["rouge", +"noir"], "en" : ["red", "black"],"de": ["rot", "schwarz"]}). +
    • +
+
    +
  • +The Query Term value target element corresponds to a +LanguageProperty and no language filter is specified e.g. color[*]!="red": +
    • +
+
    +
  • +No matching value is found in any of the values of the key-value pairs +of a languageMap (e.g. matches {"fr": +"noir", "en": "black","de": "schwarz"}, but not {"fr": "rouge", "en": "red","de": "rot"}). +
    • +
  • +No matching value is found as a single element from the array of values +of the key-value pair corresponding to the specified natural language of +the languageMap (e.g. matches {"fr": +["chat", "rouge"], "en": ["coal", "black"], "de": ["blaue", +"Engel"]} but not {"fr": ["rouge", +"noir"], "en": ["red", "black"],"de": ["rot", "schwartz"]}). +
    • +
+
    +
  • +The Query Term value is a URI and the target element corresponds to a +Relationship, a ListRelationship or a +VocabProperty, e.g. color!="http://example.com/red": +
    • +
+
    +
  • +Is not identical to the target value (e.g. matches "http://example.com/black"). +
    • +
  • +Is not included in the target value, if the latter is an array (e.g. +matches ["http://example.com/blue", +"http://example.com/black", "http://example.com/green"], +but not ["http://example.com/blue", +"http://example.com/red", "http://example.com/green"]). +
    • +
+
    +
  • +If the Query Term value target element corresponds to a +Relationship, a ListRelationship or a VocabProperty and is a list of +URIs e.g. color!="http://example.com/black", " +http://example.com/red": +
    • +
+
    +
  • +The target value is not identical to any of the list values (e.g. +matches "http://example.com/blue"). +
    • +
  • +The target value does not include any of the list values, if the target +value is an array (e.g. matches ["http://example.com/blue", +"http://example.com/yellow", "http://example.com/green"], but not +["http://example.com/blue", +"http://example.com/red", "http://example.com/green"]). +
    • +
+
    +
  • +If the data type of the target value and the data type of the Query Term +value are different, then they shall be considered unequal. +
    • +
+
    +
  • +Greater than operator (production rule named greater). For an +entity to match, it shall contain the target element and the target +value has to be strictly greater than the Query Term value: +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type then it shall be considered as not matching. +
    • +
+
    +
  • +Less than operator (production rule named less). For an +entity to match, it shall contain the target element and the target +value shall be strictly less than the value: +
    • +
+
    +
  • +If there is no equality between the target value data type and the Query +Term value data type then it shall be considered as not matching. +
    • +
+
    +
  • +Greater or equal than (production rule named greaterEq). A +matching entity shall meet any of the Greater than or the +Equal conditions for single values. +
    • +
  • +Less or equal than (production rule named lessEq). A matching +entity shall meet any of the Less than or the Equal +conditions for single values. +
    • +
  • +Match pattern (production rule named patternOp). A +matching entity shall contain the target element and the target value +shall be in the L(R) of the regular pattern specified by the Query Term: +
    • +
+
    +
  • +If the target value data type is different than String then it +shall be considered as not matching. +
    • +
+
    +
  • +Do not match pattern (production rule named +notPatternOp). A matching entity shall contain the target element +and the target value shall not be in the L(R) of the regular pattern +specified by the Query Term: +
    • +
+
    +
  • +If the target value data type is different than String then it +shall be considered as not matching. +
    • +
+

4.10 NGSI-LD +Geoquery Language

+

The NGSI-LD Geoquery language shall be supported by implementations. +It is intended to define predicates which allow testing whether a +specific topological spatial relationship exists between a pair of +geometries: a target geometry and a reference geometry. The target +geometry represents a geospatial Property of an Entity, typically, the +location of the Entity.

+

A total of four parameters are defined in order to fully specify an +NGSI-LD Geoquery:

+
    +
  • +georel, to express the desired geospatial relationship; +
    • +
  • +geometry, to express the type of the reference +geometry; +
    • +
  • +coordinates, to express the reference geometry; +
    • +
  • +geoproperty, to express the target geometry of an +Entity. This parameter is optional, location is the default. +
    • +
+

The following grammar defines the syntax for the geospatial +relationships (parameter name georel):

+
+andOp = %x3B ; ; +
+
+equal = %x3D %x3D ; == +
+
+georel = nearRel / withinRel / containsRel / overlapsRel / intersectsRel +/ equalsRel / disjointRel +
+
+nearRel = nearOp andOp distance equal PositiveNumber ; +near;max(min)Distance==x (in meters) +
+
+distance = "maxDistance" / "minDistance" +
+
+nearOp = "near" +
+
+withinRel = "within" +
+
+containsRel = "contains" +
+
+intersectsRel = "intersects" +
+
+equalsRel = "equals" +
+
+disjointRel = "disjoint" +
+
+overlapsRel = "overlaps" +
+
+ +
+

PositiveNumber +shall be a non-zero positive number as mandated by the JSON +Specification. Thus, it shall follow the ABNF Grammar, production rule +named Number, +section 6 of IETF RFC 8259 [6], excluding the 'minus' +symbol and excluding the number 0.

+

Reference geometries shall be specified by:

+
    +
  • +A geometry type (parameter name geometry) as defined by +the GeoJSON specification (IETF RFC 7946 [8], section 1.4), except +GeometryCollection. +
    • +
  • +A coordinates (parameter name coordinates) element +which shall represent the coordinates of the reference geometry as +mandated by IETF RFC 7946 [8], section 3.1.1. +
    • +
+

Target geometry, i.e. the target Entity's GeoProperty to which +the geoquery is to be applied, can be specified by an extra parameter +named geoproperty. The GeoProperty's name shall +be specified as short hand name and not a fully qualified one, because, +when the query language is used, an @context properly defining +all the terms (as per clause +5.5.7) shall be issued. If no geoproperty is specified, the +geoquery is applied to the default Property location (see +clause +4.7.1).

+

Note that proper URL encoding shall be used by HTTP binding API +clients when using these examples.

+
+
+EXAMPLE 1: +
+
+ +? +georel=near;maxDistance==2000 +
+
+
+&geometry=Point +
+
+&coordinates=[8,40] +
+
+&geoproperty=observationSpace +
+
+ +
+
+
+EXAMPLE 2: +
+
+ +? +georel=within +
+
+
+
+&geometry=Polygon +
+
+
+&coordinates=[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0], +
+
+[100.0,0.0]]] +
+
+&geoproperty=location +
+
+ +
+
+
+EXAMPLE 3: +
+
+A + +query + +encoded + +as + +an + +HTTP + +Query + +String. + +Note + +that + +this + +is + +HTTP + +binding + +specific, + +to + +be + +used + +via + +GET + +method, + +as + +defined + +in + +clause 6.4.3.2 +. +
+
+
+
+ +
+
+ +
+
+
+
+&geometry=Point +
+
+&coordinates=[8,40] +
+
+ +
+
+

The semantics of the different geospatial relationships defined above +is as follows, and shall be supported by compliant implementations:

+
    +
  • +near statement (production rule named nearRel): +
    • +
+
    +
  • +maxDistance +modifier. For an entity to match it has to be within the buffer +geometric object (as defined by [14]) given by the reference +geometry, with distance (in meters) equal to the number conveyed +(production rule named PositiveNumber). +
    • +
  • +minDistance +modifier. For an entity to match it has to be disjoint with the buffer +geometric object (as defined by [14]) given by the reference +geometry, with distance (in meters) equal to the number conveyed +(production rule named PositiveNumber). +
    • +
+
    +
  • +equals relationship (production rule named equalsRel). For an +entity to match, the target geometry shall be equal, as specified by +[14], to the +reference geometry. +
    • +
  • +disjoint relationship (production rule named disjointRel). For +an entity to match, the target geometry shall be disjoint, as specified +by [14], to the +reference geometry. +
    • +
  • +intersects relationship (production rule named intersectsRel). For +an entity to match, the target geometry shall intersect, as specified by +[14], with the +reference geometry. +
    • +
  • +within relationship (production rule named +withinRel). For an entity to match, the target geometry shall be +within, as specified by [14], the reference geometry. +
    • +
  • +contains relationship (production rule named containsRel). For +an entity to match, the target geometry shall contain, as specified by +[14], the reference +geometry. +
    • +
  • +overlaps relationship (production rule named overlapsRel). For +an entity to match, the target geometry shall overlap, as specified by +[14], the reference +geometry. +
    • +
+

When resolving geo-queries, Entities which do not convey the target +GeoProperty of the query shall be considered as non-matching.

+

4.11 NGSI-LD Temporal Query +Language

+

The NGSI-LD Temporal Query language shall be supported by +implementations. It is intended to define predicates which allow testing +whether Temporal Properties of NGSI-LD Entities, Properties and +Relationships, are within certain temporal constraints. In particular it +can be used to request historic Property values and Relationships that +were valid within the specified timeframe.

+

The following grammar defines the syntax that shall be supported:

+
+timerel = beforeRel / afterRel / betweenRel +
+
+beforeRel = "before" +
+
+afterRel = "after" +
+
+betweenRel = "between" +
+
+ +
+

The points in time for comparison are defined as follows:

+
    +
  • +A timeAt parameter, which shall represent the +comparison point for the before and after relation and the +starting point for the between relation. It shall be represented +as DateTime (mandated by clause +4.6.3). +
    • +
  • +An endTimeAt parameter, which is only used for the +between relation and shall represent the end point for +comparison. It shall be represented as DateTime (mandated by clause +4.6.3). +
    • +
+

The Temporal Property (see clause +4.8) to which the temporal query is to be applied can be specified +by timeproperty. If no timeproperty is +specified, the temporal query is applied to the default Temporal +Property observedAt.

+
+
+EXAMPLE 1: +
+
+ +? +timerel=before +
+
+
+&timeAt=2017-12-13T14:20:00Z +
+
+ +
+
+
+EXAMPLE 2: +
+
+ +? +timerel=between +
+
+
+&timeAt=2017-12-13T14:20:00Z +
+
+&endTimeAt=2017-12-13T14:40:00Z +
+
+&timeproperty=modifiedAt +
+
+ +
+
+
+EXAMPLE 3: +
+
+Temporal + +query + +encoded + +as + +HTTP + +Query + +String, + +note + +that + +this + +is + +HTTP + +binding + +specific, + +to + +be + +used + +via + +GET + +method, + +as + +defined + +in + +clause 6.18.3.2 +. +
+
+
+
+ +
+
+ +
+
+
+
+&timeproperty=observedAt +
+
+&timeAt=2017-12-13T14:20:00Z +
+
+ +
+
+

The semantics of the different temporal relations defined above is as +follows, and shall be supported by compliant implementations:

+
    +
  • +before relationship (production rule named beforeRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be before the time specified by +timeAt; +
    • +
  • +after relationship (production rule named afterRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be after the time specified by +timeAt; +
    • +
  • +between relationship (production rule named betweenRel). For a +Temporal Property to match, the value of the specified Temporal Property +(or observedAt as default) has to be after the time specified by +timeAt and before the time specified by endTimeAt. +
    • +
+

When resolving temporal queries, Entities which do not convey the +target Temporal Property of the query shall be considered as +non-matching.

+

4.12 NGSI-LD +Pagination

+

NGSI-LD operations can potentially return a result set including a +large number of NGSI-LD Elements, so that pagination of query results +shall be supported by compliant implementations.

+

The list of operations that incur this behaviour is as follows:

+ +

Nonetheless, the NGSI-LD API is agnostic about specific pagination +mechanisms and only defines the behaviour that shall be observed by +NGSI-LD Systems.

+

For each operation above, NGSI-LD Systems shall:

+
    +
  • +provide a mechanism to iterate through the NGSI-LD Elements of a result +set without exhausting NGSI-LD Client or Broker resources; +
    • +
  • +provide a mechanism to flag NGSI-LD Clients when there are remaining +NGSI-LD Elements to be traversed as part of a result set; +
    • +
  • +allow NGSI-LD Clients specifying a limit (page size), as a parameter of +API operations, to the number of NGSI-LD Elements (at a maximum) +retrieved by the implementation for each pagination iteration; +
    • +
  • +define a default limit (default page size) to the +number of NGSI-LD Elements retrieved per pagination iteration; +
    • +
  • +allow NGSI-LD Clients iterating forwards and backwards through a result +set. +
    • +
+

NGSI-LD implementations should:

+
    +
  • +avoid Denial of Service attacks or other potential security risks, by +defining a hard limit to the size of generated response payload body +while paginating. For instance, certain queries can be rejected by +issuing an error of type TooManyResults. +
    • +
+

NGSI-LD implementations may:

+
    +
  • +warn NGSI-LD Clients when result sets become invalid due to dynamic +changes in NGSI-LD Elements (additions, deletions) occurred while +iterating over pages. +
    • +
+

The concrete realization of the features described above might depend +on each API binding. Nonetheless, NGSI-LD Systems shall implement +pagination features as mandated by the present clause, for any API +binding.

+

4.13 Counting the Number of +Results

+

Given that NGSI-LD Query operations can potentially return a result +set including a large number of NGSI-LD Elements and that pagination of +query results shall be supported (see clause +4.12), compliant implementations shall also support a mechanism for +relaying to the client the number of expected resulting elements, when a +query is executed.

+

A specific field (e.g. a custom header in the response in case of +HTTP binding, see clause +6.3.13) shall be returned within the response of a query, whenever +this is requested by the client.

+

Mechanisms for limiting the number of returned NGSI-LD Elements are +independent of the counting mechanism, so that, potentially, a client +can issue a query that limits to zero the number of desired results but +asks for the count to be present.

+

This is useful for client-side planning and fine-tuning of subsequent +queries and their parameters.

+

4.14 Supporting Multiple Tenants

+

The concept of a Tenant is that a +user or group of users utilizes a single instance of an NGSI-LD system +(Context Source or Context Broker) in isolation from other +users or groups of users of the same instance, which are considered to +be different Tenants. Thus a multi-tenant NGSI-LD system is a +system where a single software instance is used by different users or +groups of users, the Tenants, where 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. Typically, multi-tenancy is +used together with an access control mechanism, enforcing the isolation +of Tenants, however access control and other +security-related aspects are out-of-scope of the present document.

+

The NGSI-LD API optionally enables multi-tenant systems. To support +this, Tenant information can be +optionally specified in NGSI-LD API operations. The operation then only +applies to the targeted Tenant. As +all information of one Tenant is +isolated from other Tenants, the NGSI-LD API operations for managing, +retrieving and subscribing to entity information, but also any context +source related operations only apply to the information of the specified +Tenant in isolation and never have +any effect on the information of other Tenants.

+

As the support and use of Tenants +is optional, any operation not explicitly specifying a Tenant targets a default Tenant, which always exists. NGSI-LD +systems not supporting multiple Tenants +should raise an error of type NoMultiTenantSupport if a Tenant is specified. To enable Context Sources to be part of tenant-based +distributed or federated systems, Tenant information can optionally be +specified in Context Source +Registrations. When contacting the respective Context Sources, the Tenant information from the Context Source Registration has to be used. +If no Tenant information is present +in the Context Source Registration, +no Tenant information is to be used +and thus the default Tenant is +targeted on the registered Context +Source. This enables integrating Context Sources not supporting +multi-tenancy in a distributed system with a Tenant-based Context Broker or integrating local Tenants +in a federated system using a different Tenant.

+

4.15 NGSI-LD +Language Filter

+

The NGSI-LD Language Filter shall be supported by implementations. It +is intended to form a mechanism which allows just one matching string +value of LanguageProperties of NGSI-LD Entities to be converted +to an NGSI-LD Property, where the value will be a string for the +specified natural language.

+

The following grammar defines the syntax that shall be supported by +the filter:

+
+lang = langtag +
+
+ +
+

Where the langtag is defined according to the rules as mandated by +IETF RFC 5646 [28], +and IETF RFC 3282 [29]. If the Context Broker cannot serve any matching +language, it shall default to any supported language. This behavior can +be triggered by specifying lang="*" in the filter (see +example 3).

+

In any case, the attribute in question shall be augmented with an +additional non-reified subproperty lang indicating the actual +language returned.

+
+
+EXAMPLE 1: +
+
+Specified + +natural + +language + +- + +return + +LanguageProperties + +as + +strings + +in + +English + +only. +
+
+
+ lang="en" +
+
+
+EXAMPLE 2: +
+
+Multiple + +natural + +languages + +with + +no + +ranked + +preference + +- + +return + +LanguageProperties + +as + +strings + +in + +either + +Swiss + +French + +or + +French. +
+
+
+ lang="fr-CH,fr" +
+
+
+EXAMPLE 3: +
+
+Wildcard + +- + +return + +LanguageProperties + +as + +a + +string + +in + +any + +supported + +language. +
+
+
+ lang="*" +
+
+
+EXAMPLE 4: +
+
+Quality + +value + +ranking + +- + +return + +all + +LanguageProperties + +as + +a + +string + +in + +Swiss + +French + +or + +French + +with + +no + +ranked + +preference, + +fallback + +to + +English + +as + +a + +second + +choice + +and + +finally + +fallback + +to + +any + +other + +supported + +language. +
+
+
+ lang="fr-CH,fr;q=0.9,en;q=0.8,*;q=0.5" +
+

4.16 Supporting Multiple Entity +Types

+

From NGSI-LD API version 1.5.1 onwards, multiple Entity Types for any +Entity are supported. An Entity is uniquely identified by its id, so +whenever information is provided for an Entity with a given id, it is +considered part of the same Entity, regardless of the Entity Type(s) +specified. To avoid unexpected behaviour, Entity Types can be implicitly +added by all operations that update or append attributes. There is no +operation to remove Entity Types from an Entity. The philosophy here is +to assume that an Entity always had all Entity Types, but possibly not +all Entity Types have previously been known in the system. The only +option to remove an Entity Type is to delete the Entity and re-create it +with the same id. Alternatively, a batch upsert with 'replace' update +mode can be used, as described in clause +5.6.8.

+

4.17 NGSI-LD Entity Type +Selection Language

+

The NGSI-LD Entity Type Selection Language shall be supported by +implementations. It is intended to select only those Entities that have +the specified Entity Type(s), possibly among others. Entity Types are +specified as a disjunction of elements, where each element can either +directly be an Entity Type or a conjunction of multiple Entity Types. +The logical operators are the same as in the NGSI-LD Query Language +specified in clause +4.9. As a disjunction of Entity Types can also be seen as a list, +and to be compatible with previous versions of the NGSI-LD API, a comma +can be used as an alternative representation of the or operator. +For logical and grouping parenthesis are needed.

+
+EntityTypes = OrEntityType *(orOp OrEntityType) ; OrEntityType|OrEntityType +
+
+OrEntityType = %x28 EntityType *(andOp EntityType) %x29             ; (EntityType;EntityType) +
+
+OrEntityType = EntityType                        ; EntityType +
+
+andOp = %x3B                        ; ; +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ +
+

EntityType is +either a valid name as specified in clause +4.6.2 or a URI.

+
+
+EXAMPLE 1: +
+
+Entities + +of + +type + +Building + +or + +House: +
+
+
+Building|House +
+
+
+ +
+
+ +
+
+
+Building,House +
+
+
+EXAMPLE 2: +
+
+Entities + +of + +type + +Home + +and + +Vehicle: +
+
+
+(Home;Vehicle) +
+
+
+EXAMPLE 3: +
+
+Entities + +of + +type + +(Home + +and + +Vehicle) + +or + +Motorhome: +
+
+
+(Home;Vehicle)|Motorhome +
+
+
+ +
+
+ +
+
+
+(Home;Vehicle),Motorhome +
+
+
+NOTE: +
+
+The + +special + +characters + +"," +, + +";" +, + +"(" + +and + +")" + +used + +in + +the + +Entity + +Type + +Selection + +Language + +are + +allowed + +characters + +in + +URIs. + +The + +use + +of + +short + +names + +is + +recommended. +
+
+

4.18 NGSI-LD Scopes

+

An NGSI-LD Scope enables putting Entities into a hierarchical +structure and restrict results of queries and notifications accordingly. +The hierarchical structure is user-defined, e.g. according to (logical) +location or organization. The use of Scopes is optional and an Entity +can be assigned to one or more Scopes at the same time. The Scope is +represented as a special scope Property that is non-reified in +the normalized Entity representation and reified in the temporal +representation of an Entity. In the latter case, it is restricted to +having the non-reified Temporal Properties createdAt, modifiedAt +and deletedAt as sub-Properties. There shall at most be one +instance of the scope property per Entity. In case multiple +representations of the same Entity have to be merged, e.g. when +combining the results of distributed queries, the values of scope +are merged. The value of scope is represented as a JSON +array in case there is more than one Scope. For the Temporal Evolution a +given Scope is considered valid from the time it has been set until the +time it has been explicitly removed by an update or delete operation +(for an example see annex +C, clause +C.5.16).

+

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

+
+Scope = [%x2F] ScopeLevel *(%x2F ScopeLevel)                        ; [/] ScopeLevel *(/ScopeLevel) +
+
+ScopeLevel = unicodeLetter *ScopeLevelChar +
+
+ScopeLevelChar = unicodeNumber / unicodeLetter +
+
+ScopeLevelChar =/ %x5F                                              ; _ +
+
+ +
+
+
+EXAMPLE 1: +
+
+ +/Madrid +
+
+
+
+EXAMPLE 2: +
+
+ + +Madrid +
+
+
+
+EXAMPLE 3: +
+
+ +/Madrid/Gardens/ParqueNorte +
+
+
+
+EXAMPLE 4: +
+
+ +/CompanyA/OrganizationB/UnitC +
+
+

4.19 NGSI-LD +Scope Query Language

+

The NGSI-LD Scope Query Language shall be supported by +implementations. It is intended to select only those Entities that are +within the specified Scope(s). Scopes are specified as a disjunction of +elements, where each element can either directly be a Scope or a +conjunction of multiple Scopes. The "+" +can be used as a wildcard to match a single scope level within a Scope. +The "#" that can be added at the end of a +Scope specification serves as a wildcard, which matches the given scope +and the whole hierarchy of scopes below. The "/#" matches any non-empty scope, i.e. only +explicitly specified scopes. The logical operators are the same as in +the NGSI-LD Query Language specified in clause +4.9. As a disjunction of Scopes can also be seen as a list, a comma +can be used as an alternative representation of the or operator. +For logical and grouping parenthesis are needed.

+
+ScopesQ = OrScopeQ *(orOp OrScopeQ) ; OrScopeQ|OrScopeQ +
+
+ScopesQ =/ %x2F %23 ; / # +
+
+OrScopeQ = %x28 ScopeQ *(andOp ScopeQ) %x29             ; (ScopeQ;ScopeQ) +
+
+OrScopeQ =/ ScopeQ *1(%x2F %23)                          ; ScopeQ / # +
+
+andOp = %x3B                        ; ; +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ScopeQ = %x2F ScopeQLevel *(%x2F ScopeQLevel)                       ; /ScopeQLevel *(/ScopeQLevel) +
+
+ScopeQLevel = unicodeLetter *ScopeQLevelChar +
+
+ScopeQLevel =/ %x2B ; +  +
+
+ScopeQLevelChar = unicodeNumber / unicodeLetter +
+
+ScopeQLevelChar =/ %x5F                                             ; _ +
+
+ +
+
+
+EXAMPLE 1: +
+
+Scope + +/Madrid: +
+
+
+/Madrid +
+
+
+EXAMPLE 2: +
+
+Scope + +/Madrid/Gardens + +and + +the + +whole + +scope + +tree + +below: +
+
+
+/Madrid/Gardens/#, e.g. matches the +following Scopes: +
+
+/Madrid/Gardens, /Madrid/Gardens/ParqueNorte, /Madrid/Gardens/ParqueNorte/Parterre1, /Madrid/Gardens/ParqueSur +
+
+
+EXAMPLE 3: +
+
+Scopes + +/Madrid/Gardens/ParqueNorte + +and + +/Madrid/Sights/ParqueNorte, + +or + +any + +other + +Scope + +with + +Madrid + +as + +first + +scope + +level + +and + +ParqueNorte + +as + +third + +scope + +level: +
+
+
+
+/Madrid/+/ParqueNorte +
+
+
+
+EXAMPLE 4: +
+
+Scope + +/Madrid/Districts + +and + +/CompanyA: +
+
+
+(/Madrid/Districts;/CompanyA) +
+
+
+EXAMPLE 5: +
+
+Scope + +(/Madrid/Districts + +and + +/CompanyA) + +or + +/CompanyB: +
+
+
+(/Madrid/Districts;/CompanyA)|CompanyB +
+
+
+ +
+
+ +
+
+
+(/Madrid/Districts;/CompanyA),CompanyB +
+

4.20 NGSI-LD Distributed +Operation names

+

When registering Context Sources +(see clause +5.2.9), the registrant NGSI-LD interface endpoint may optionally +offer a subset of NGSI-LD operations which it accepts. Table +4.20‑1 defines a list of names for each of these operations.

+
+Table 4.20-1: Names of implemented Operations +
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+Operation name +
+Implements +
+Context Information Provision +
+createEntity +
+5.6.1 Create Entity +
+updateEntity +
+5.6.2 Update Attributes +
+appendAttrs +
+5.6.3 Append Attributes +
+updateAttrs +
+5.6.4 Partial Attribute update +
+deleteAttrs +
+5.6.5 Delete Attribute +
+deleteEntity +
+5.6.6 Delete Entity +
+createBatch +
+5.6.7 Batch Entity Creation +
+upsertBatch +
+5.6.8 Batch Entity Creation or Update (Upsert) +
+updateBatch +
+5.6.9 Batch Entity Update +
+deleteBatch +
+5.6.10 Batch Entity Delete +
+upsertTemporal +
+5.6.11 Create or Update Temporal Evolution of an Entity +
+appendAttrsTemporal +
+5.6.12 Add Attributes to Temporal Evolution of an Entity +
+deleteAttrsTemporal +
+5.6.13 Delete Attributes from Temporal Evolution of an Entity +
+updateAttrInstanceTemporal +
+5.6.14 Partial Update Attribute Instance in Temporal Evolution of an +Entity +
+deleteAttrInstanceTemporal +
+5.6.15 Delete Attribute Instance from Temporal Evolution of an Entity +
+deleteTemporal +
+5.6.16 Delete Temporal Evolution of an Entity +
+mergeEntity +
+5.6.17 Merge Entity +
+replaceEntity +
+5.6.18 Replace Entity +
+replaceAttrs +
+5.6.19 Replace Attribute +
+mergeBatch +
+5.6.20 Batch Entity Merge +
+purgeEntity +
+5.6.21 Purge Entities +
+Context Information Consumption +
+retrieveEntity +
+5.7.1 Retrieve Entity +
+queryEntity +
+5.7.2 Query Entities (excluding batch entity queries) +
+queryBatch +
+5.7.2 Query Entities (batch entity queries only) +
+retrieveTemporal +
+5.7.3 Retrieve Temporal Evolution of an Entity +
+queryTemporal +
+5.7.4 Query Temporal Evolution of Entities +
+retrieveEntityTypes +
+5.7.5 Retrieve Available Entity Types +
+retrieveEntityTypeDetails +
+5.7.6 Retrieve Details of Available Entity Types +
+retrieveEntityTypeInfo +
+5.7.7 Retrieve Available Entity Type Information +
+retrieveAttrTypes +
+5.7.8 Retrieve Available Attributes +
+retrieveAttrTypeDetails +
+5.7.9 Retrieve Details of Available Attributes +
+retrieveAttrTypeInfo +
+5.7.10 Retrieve Available Attribute Information +
+Context Information Subscription +
+createSubscription +
+5.8.1 Create Subscription +
+updateSubscription +
+5.8.2 Update Subscription +
+retrieveSubscription +
+5.8.3 Retrieve Subscription +
+querySubscription +
+5.8.4 Query Subscription +
+deleteSubscription +
+5.8.5 Delete Subscription +
+Support operations for distributed operations +
+retrieveEntityMap +
+5.14.1 Retrieve EntityMap +
+updateEntityMap +
+5.14.2 Update EntityMap +
+deleteEntityMap +
+5.14.3 Delete EntityMap +
+createEntityMapQueryEntity +
+5.14.4 Create EntityMap for Query Entities +
+createEntityMapQueryTemporal +
+5.14.5 Create EntityMap for Query Temporal Evolution of Entities +
+retrieveContextSourceIdentity +
+5.15.1 Retrieve Context Source Identity Information +
+

In addition to these individual operations, a series of names for +common groups of operations have also been defined. Table +4.20‑2 defines a list of names for each of these operation +groups.

+
+Table 4.20-2: Named Operation Groups +
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Operation Group name +
+Implements +
+federationOps +
    +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
  • +queryBatch +
    • +
  • +retrieveEntityTypes +
    • +
  • +retrieveEntityTypeDetails +
    • +
  • +retrieveEntityTypeInfo +
    • +
  • +retrieveAttrTypes +
    • +
  • +retrieveAttrTypeDetails +
    • +
  • +retrieveAttrTypeInfo +
    • +
  • +createSubscription +
    • +
  • +updateSubscription +
    • +
  • +retrieveSubscription +
    • +
  • +querySubscription +
    • +
  • +deleteSubscription +
    • +
  • +retrieveEntityMap +
    • +
  • +updateEntityMap +
    • +
  • +deleteEntityMap +
    • +
  • +createEntityMapQueryEntity +
    • +
  • +retrieveContextSourceIdentity +
    • +
+associationOps +
+updateOps +
    +
  • +updateEntity +
    • +
  • +updateAttrs +
    • +
  • +replaceEntity +
    • +
  • +replaceAttrs +
    • +
+retrieveOps +
    +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
+redirectionOps +
    +
  • +createEntity +
    • +
  • +updateEntity +
    • +
  • +appendAttrs +
    • +
  • +updateAttrs +
    • +
  • +deleteAttrs +
    • +
  • +deleteEntity +
    • +
  • +mergeEntity +
    • +
  • +replaceEntity +
    • +
  • +replaceAttrs +
    • +
  • +retrieveEntity +
    • +
  • +queryEntity +
    • +
  • +purgeEntity +
    • +
  • +retrieveEntityTypes +
    • +
  • +retrieveEntityTypeDetails +
    • +
  • +retrieveEntityTypeInfo +
    • +
  • +retrieveAttrTypes +
    • +
  • +retrieveAttrTypeDetails +
    • +
  • +retrieveAttrTypeInfo +
    • +
  • +retrieveEntityMap +
    • +
  • +updateEntityMap +
    • +
  • +deleteEntityMap +
    • +
  • +createEntityMapQueryEntity +
    • +
  • +retrieveContextSourceIdentity +
    • +
+

If no specific subset of operations is defined for a Context Source Registration, the default +set of operations matches the group defined as "federationOps".

+

4.21 NGSI-LD Attribute +Projection Language

+

The NGSI-LD Attribute Projection Language shall be supported by +implementations for projection parameters (e.g. pick and +omit). Its aim is to specify the Attributes to be retrieved +within an Entity (or associated Linked +Entities when Linked Entity Retrieval is used). Projected +Attributes are specified as a disjunction of elements, where each +element can either directly be an Attribute name, or in the case of +Linked Entity Retrieval, a Relationship name followed by an Attribute +name within the Linked Entity. Since +a disjunction of Attributes is a list, either a comma or a pipe +character can be used as alternative representations of the or +operator. In the following, ABNF grammar for NGSI-LD Attribute +Projection Language is given.

+
+ +
+
+orOp = %x7C / %x2C                                                  ; |  , +
+
+ProjectionTerm = AttrName *1(LinkedEntityTerm) *(orOp ProjectionTerm) +
+
+LinkedEntityTerm  = %x7B ProjectionTerm %x7D ; {ProjectionTerm} +
+
+ +
+

See clause +4.9 for the definition of AttrName.

+
+
+EXAMPLE 1: +
+
+ +?pick=temperature +
+
+
+
+EXAMPLE 2: +
+
+ +?pick=temperature,humidity +
+
+
+
+EXAMPLE 3: +
+
+ +?pick=observation{temperature,humidity} +
+
+

4.22 Transient Storage +of Entities and Attributes

+

In some cases, it is desirable to create an Entity (or Attribute) +which is only expected to be stored for a defined period of time. +Thereafter such an Entity (or Attribute) should be removed, and can be +safely deleted from the context via an automatic garbage collection +process.

+

In this regard NGSI-LD defines the following system Property of type +TemporalProperty that shall be supported by implementations:

+
    +
  • +expiresAt is defined as the system temporal Property at +which a certain Entity, Property or Relationship shall become invalid +and may be automatically removed from the Context Broker. For example, +an Alert Entity was created to last for 24 hours and should be removed +after this period of time. +
    • +
+

It should be noted that clean-up processes will only run +periodically, and will be dependent upon the Context Broker +implementation, therefore final deletion will always lag the +expiresAt timestamp to a certain extent. Furthermore, +expiresAt only applies to the local storage, i.e. the Entity or +Attribute is to be deleted locally, but not on other Context Sources or +Context Broker hosting such Entity information, where no +expiresAt timestamp is present. Thus expiresAt is not +considered to be intrinsic to the Entity or Attribute, but only applies +to the storage of the Entity or Attribute respectively. As it pertains +to a system function (the deletion from storage after the expiration +time), it is considered to be a system attribute.

+ + diff --git a/public/9-tabdefinition-of-terms-symbols-and-abbreviations.html b/public/9-tabdefinition-of-terms-symbols-and-abbreviations.html new file mode 100644 index 0000000000000000000000000000000000000000..839e8c9776f2b272b22843d323dc8b3fe4a35173 --- /dev/null +++ b/public/9-tabdefinition-of-terms-symbols-and-abbreviations.html @@ -0,0 +1,3125 @@ + + + + + + + 3 Definition of terms, symbols and abbreviations + + + + + + + +
+

3 Definition of +terms, symbols and abbreviations

+

3.1 Terms

+

For the purposes of the present document, the following terms +apply:

+
+NOTE 1: The letters "NGSI-LD" were added to most terms to confirm that +they are distinct from other terms of similar/same name in use in other +organizations, however, in the present document the letters "NGSI-LD" +are generally omitted for brevity. +
+
+NOTE 2: The use of URI in the context of the present document also +includes the use of International Resource Identifiers (IRIs) as defined +in IETF RFC 3987 [23], which extends the use of +characters to Unicode characters [22] beyond the ASCII +character set, enabling the support of languages other than English. +
+

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

+
+NOTE: It is used by Distribution +Brokers and Federation Brokers +to find the appropriate Context +Sources which can provide the information required for serving an +NGSI-LD request. +
+

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

+
+NOTE: It is usually registered with an NGSI-LD Registry so that it can +announce what kind of information it can provide, when requested, to +Context Consumers and Brokers. +
+

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

+
+NOTE: In the NGSI-LD API, any instance of such an entity is +uniquely identified by a URI, and characterized by +reference to one or more NGSI-LD Entity Type(s). +
+

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

+
+NOTE: In the NGSI-LD API, an NGSI-LD Entity Type is uniquely +identified by a URI. +
+
+EXAMPLE 1: "Vehicle" is an NGSI-LD Entity +Type and is identified with a proper URI. +
+
+EXAMPLE 2: Bob's private car whose plate number is "ABCD1234" is an NGSI-LD Entity whose NGSI-LD +Entity Type name is "Vehicle". +
+
+EXAMPLE 3: Alice's motorhome has a unique URI as id, but can be assigned +multiple NGSI-LD Entity types, e.g. "Vehicle" and "Home". +
+

NGSI-LD External Linked Entity: Linked Entity that is identified through a +dereferenceable URI which does not exist within the +current NGSI-LD system

+
+NOTE: It can exist within another NGSI-LD system or within a non-NGSI-LD +system. +
+
+EXAMPLE: An NGSI-LD Entity, whose Entity Type name is "Book", can be externally linked, through the +"wasWrittenBy" relationship, to a +resource identified by the URI "http://dbpedia.org/resource/Mark_Twain". +
+

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

+
+EXAMPLE: An NGSI-LD Entity, whose Entity Type name is "Vehicle", can be internally linked, through +the "isParkedAt" relationship, to another +NGSI-LD Entity, of Type name "Parking", +identified by the URI "urn:ngsi-ld:Parking:Downtown1". +
+

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

+
+
+EXAMPLE: "A bus route services the following bus stops" can be +represented by an NGSI-LD ListRelationship whose name is "route" +which holds an array of directed links towards a series of NGSI-LD +Entities of type (Type name) "BusStop" +
+
+

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

+
+EXAMPLE: "Bob's vehicle is currently parked on a street which is known as +'Grand Place' in French and 'Grote Markt' in Dutch" can be represented +by an NGSI-LD LanguageProperty whose name is "street" which holds an NGSI-LD Map of two +key-value pairs containing both the French ("fr") and Dutch ("nl") exonyms of the street name. +
+

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

+
+EXAMPLE: "Bob's vehicle's speed is 40 km/h" can be represented by an +NGSI-LD Property, whose name is "speed", and which characterizes an +NGSI-LD Entity, whose NGSI-LD Type is "Vehicle". Such a name can be expanded to a +fully qualified name in the form of a URI, for instance "http://example.org/Vehicle" or "http://example.org/speed". +
+

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

+
+EXAMPLE 1: An NGSI-LD Entity of type "Vehicle" can be the subject of an NGSI-LD +Relationship whose object is an NGSI-LD Entity of type "Parking". +
+
+EXAMPLE 2: An NGSI-LD Entity of type "Vehicle" can be the subject of an NGSI-LD +Relationship whose object is an array of NGSI-LD Entities of type "Passenger". +
+

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)

+
+EXAMPLE: Bob's private car 'speed' NGSI-LD Value is the number 100 +(kilometres per hour). +
+

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

+
+EXAMPLE: "Bob's car is a non-commercial vehicle" can be represented by an +NGSI-LD VocabProperty whose name is +"category" which holds the string value +"non-commercial". If the associated +JSON-LD context defines the term "non-commercial" as "http://example.com/non-commercial", then the +returned value shall be expanded using JSON-LD type coercion into the +URI the "http://example.com/non-commercial" +
+

3.2 Symbols

+

Void.

+

3.3 Abbreviations

+

For the purposes of the present document, the following abbreviations +apply:

+
+ABNF Augmented Backus-Naur Form +
+
+ALG1 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document +
+
+AM Ante Meridiem +
+
+API Application Programming Interface +
+
+ASCII American Standard Code for Information Interchange +
+
+BNF Backus Naur Form +
+
+CH Switzerland +
+
+CSR Context Source Registration +
+
+ECMA European Computer Manufacturers Association +
+
+EU European Union +
+
+FI Future Internet +
+
+FQN Fully Qualified Name +
+
+GB Great Britain +
+
+GDPR General Data Protection Regulation +
+
+GeoJSON Geographic JavaScript Object Notation +
+
+GeoJSON-LD Geographic JavaScript Object Notation - Linked Data +
+
+GIS Geographic Information System +
+
+GPS Global Positioning System +
+
+HTTP Hypertext Transfer Protocol +
+
+HTTPS Hypertext Transfer Protocol Secure +
+
+IANA Internet Assigned Numbers Authority +
+
+ID Identifier +
+
+IEEE Institute of Electrical and Electronics Engineers +
+
+IETF Internet Engineering Task Force +
+
+IoT Internet of Things +
+
+IRI Internationalized Resource Identifier +
+
+ISG Industry Specification Group +
+
+ISO International Organization for Standardization +
+
+JSON JavaScript Object Notation +
+
+JSON-LD JSON Linked Data +
+
+LD Linked Data +
+
+LWM2M LightWeight Machine to Machine +
+
+M2M Machine to Machine +
+
+MIME Multi-purpose Internet Mail Extensions +
+
+MQTT Message Queuing Telemetry Transport +
+
+N/A Not Applicable +
+
+NGSI Next Generation Service Interfaces +
+
+NGSILD Next Generation Service +Interfaces Linked Data (same as NGSI-LD) +
+
+NID Namespace Identifier +
+
+NSS Namespace Specific String +
+
+OAS Open API Specification +
+
+OMA Open Mobile Alliance +
+
+oneM2M oneM2M Partnership Project +
+
+PM Post Meridiem +
+
+POSIX Portable Operating System Interface +
+
+QoS Quality of Service +
+
+RDF Resource Description Format +
+
+REST Representational State Transfer +
+
+RFC Request For Comments +
+
+SAREF Smart Applications Reference ontology +
+
+TCP Transport Control Protocol +
+
+TLS Transport Layer Security +
+
+TS Technical Specification +
+
+UCA Unicode Collation Algorithm +
+
+UL Ultra Light +
+
+UML Unified Modelling Language +
+
+URI Uniform Resource Identifier +
+
+URL Universal Resource Locator +
+
+URN Uniform Resource Name +
+
+UTC Coordinated Universal Time +
+
+UTF Unicode (or Universal Coded Character Set) Transformation Format +
+
+XSD XML Schema Definition +
+
+ + diff --git a/public/editing/.gitkeep b/public/editing/.gitkeep deleted file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/public/index.html b/public/index.html index 2f1c765a103ffe1399cc30501ecbcd3257f3384c..05965577d0f87c68301c3b8fc2eaa453692d65ee 100644 --- a/public/index.html +++ b/public/index.html @@ -1,48 +1,2760 @@ - - - - - - - -
- - -
- - - - \ No newline at end of file + + + + + + temp + + + + + + + + +
+ + diff --git a/API/media/annex.json b/public/media/annex.json similarity index 100% rename from API/media/annex.json rename to public/media/annex.json diff --git a/API/media/image10.emf b/public/media/image10.emf similarity index 100% rename from API/media/image10.emf rename to public/media/image10.emf diff --git a/public/media/image10.png b/public/media/image10.png new file mode 100644 index 0000000000000000000000000000000000000000..2bdc94bfc10ba083b388d9d6190732be4f6ba683 Binary files /dev/null and b/public/media/image10.png differ diff --git a/API/media/image110.emf b/public/media/image100.emf similarity index 100% rename from API/media/image110.emf rename to public/media/image100.emf diff --git a/public/media/image100.png b/public/media/image100.png new file mode 100644 index 0000000000000000000000000000000000000000..77831040ce6d4cab501e7763efad61761dd6242e Binary files /dev/null and b/public/media/image100.png differ diff --git a/public/media/image101.emf b/public/media/image101.emf new file mode 100644 index 0000000000000000000000000000000000000000..f5f7d286a724d38842c6977eff978a7674f44c2c Binary files /dev/null and b/public/media/image101.emf differ diff --git a/public/media/image101.png b/public/media/image101.png new file mode 100644 index 0000000000000000000000000000000000000000..759f53d3caaaf84672fcbffe536aa8d7919f2f1e Binary files /dev/null and b/public/media/image101.png differ diff --git a/public/media/image102.emf b/public/media/image102.emf new file mode 100644 index 0000000000000000000000000000000000000000..172af29e293e8e57b3ac52a399cd7bbdc9813b32 Binary files /dev/null and b/public/media/image102.emf differ diff --git a/public/media/image102.png b/public/media/image102.png new file mode 100644 index 0000000000000000000000000000000000000000..269417105270faf5bbe22c9095ed2ff5951a2329 Binary files /dev/null and b/public/media/image102.png differ diff --git a/API/media/image113.emf b/public/media/image103.emf similarity index 100% rename from API/media/image113.emf rename to public/media/image103.emf diff --git a/public/media/image103.png b/public/media/image103.png new file mode 100644 index 0000000000000000000000000000000000000000..fcfc49be05d01c9a2da9566a16ebc7d6908d88ad Binary files /dev/null and b/public/media/image103.png differ diff --git a/API/media/image114.emf b/public/media/image104.emf similarity index 100% rename from API/media/image114.emf rename to public/media/image104.emf diff --git a/public/media/image104.png b/public/media/image104.png new file mode 100644 index 0000000000000000000000000000000000000000..8023762f80b14a3c1920d549759ef12ff19052ba Binary files /dev/null and b/public/media/image104.png differ diff --git a/API/media/image115.emf b/public/media/image105.emf similarity index 100% rename from API/media/image115.emf rename to public/media/image105.emf diff --git a/public/media/image105.png b/public/media/image105.png new file mode 100644 index 0000000000000000000000000000000000000000..6211fe54a438040fff52d80f664ec317503484c8 Binary files /dev/null and b/public/media/image105.png differ diff --git a/API/media/image116.emf b/public/media/image106.emf similarity index 100% rename from API/media/image116.emf rename to public/media/image106.emf diff --git a/public/media/image106.png b/public/media/image106.png new file mode 100644 index 0000000000000000000000000000000000000000..93c442b1a2143ce77d0fe2e72e813650efc80d1a Binary files /dev/null and b/public/media/image106.png differ diff --git a/API/media/image117.emf b/public/media/image107.emf similarity index 100% rename from API/media/image117.emf rename to public/media/image107.emf diff --git a/public/media/image107.png b/public/media/image107.png new file mode 100644 index 0000000000000000000000000000000000000000..ed6b1f004fefb68350ded2155f94317a83df2e5d Binary files /dev/null and b/public/media/image107.png differ diff --git a/public/media/image108.emf b/public/media/image108.emf new file mode 100644 index 0000000000000000000000000000000000000000..9320aea53e6bf5961f9bac43767f0dfc0abf36ff Binary files /dev/null and b/public/media/image108.emf differ diff --git a/public/media/image108.png b/public/media/image108.png new file mode 100644 index 0000000000000000000000000000000000000000..32b927f038565f5fd2752cf73b6eb37b302ca2a1 Binary files /dev/null and b/public/media/image108.png differ diff --git a/public/media/image109.emf b/public/media/image109.emf new file mode 100644 index 0000000000000000000000000000000000000000..dd9299f7c787c902413b19884619711c5b61f4c3 Binary files /dev/null and b/public/media/image109.emf differ diff --git a/public/media/image109.png b/public/media/image109.png new file mode 100644 index 0000000000000000000000000000000000000000..026eeb8ccf958e8791bb18fe5637a87f94dee7ed Binary files /dev/null and b/public/media/image109.png differ diff --git a/API/media/image11.emf b/public/media/image11.emf similarity index 100% rename from API/media/image11.emf rename to public/media/image11.emf diff --git a/public/media/image11.png b/public/media/image11.png new file mode 100644 index 0000000000000000000000000000000000000000..7ad6d3e1f66405737f701776cfcce35aa08a9d5e Binary files /dev/null and b/public/media/image11.png differ diff --git a/API/media/image120.emf b/public/media/image110.emf similarity index 100% rename from API/media/image120.emf rename to public/media/image110.emf diff --git a/public/media/image110.png b/public/media/image110.png new file mode 100644 index 0000000000000000000000000000000000000000..927b87dd1b14f4e0304226fbd1c5d82ab7b91ff8 Binary files /dev/null and b/public/media/image110.png differ diff --git a/API/media/image121.emf b/public/media/image111.emf similarity index 100% rename from API/media/image121.emf rename to public/media/image111.emf diff --git a/public/media/image111.png b/public/media/image111.png new file mode 100644 index 0000000000000000000000000000000000000000..4d7bf26512639aec8b97685b4b64f5725d654915 Binary files /dev/null and b/public/media/image111.png differ diff --git a/API/media/image122.emf b/public/media/image112.emf similarity index 100% rename from API/media/image122.emf rename to public/media/image112.emf diff --git a/public/media/image112.png b/public/media/image112.png new file mode 100644 index 0000000000000000000000000000000000000000..15da21a03a807747d01c6f2ed047de8260ac4731 Binary files /dev/null and b/public/media/image112.png differ diff --git a/API/media/image123.emf b/public/media/image113.emf similarity index 100% rename from API/media/image123.emf rename to public/media/image113.emf diff --git a/public/media/image113.png b/public/media/image113.png new file mode 100644 index 0000000000000000000000000000000000000000..075fbeb393a840b5cfe8b6836200fd363a9ae025 Binary files /dev/null and b/public/media/image113.png differ diff --git a/API/media/image124.emf b/public/media/image114.emf similarity index 100% rename from API/media/image124.emf rename to public/media/image114.emf diff --git a/public/media/image114.png b/public/media/image114.png new file mode 100644 index 0000000000000000000000000000000000000000..2917554aa23ea0f7875d62d443543d4dc730fd82 Binary files /dev/null and b/public/media/image114.png differ diff --git a/API/media/image125.emf b/public/media/image115.emf similarity index 100% rename from API/media/image125.emf rename to public/media/image115.emf diff --git a/public/media/image115.png b/public/media/image115.png new file mode 100644 index 0000000000000000000000000000000000000000..9e873ca25de82be68f6e08d6d05a0a0b98ed8ca7 Binary files /dev/null and b/public/media/image115.png differ diff --git a/API/media/image126.emf b/public/media/image116.emf similarity index 100% rename from API/media/image126.emf rename to public/media/image116.emf diff --git a/public/media/image116.png b/public/media/image116.png new file mode 100644 index 0000000000000000000000000000000000000000..6e387b3af6f08a7210d38f68e72dd5786c0dd7f1 Binary files /dev/null and b/public/media/image116.png differ diff --git a/API/media/image127.emf b/public/media/image117.emf similarity index 100% rename from API/media/image127.emf rename to public/media/image117.emf diff --git a/public/media/image117.png b/public/media/image117.png new file mode 100644 index 0000000000000000000000000000000000000000..f8d5dbe96bdaa10364bf426c61ca387cf60872e0 Binary files /dev/null and b/public/media/image117.png differ diff --git a/API/media/image128.emf b/public/media/image118.emf similarity index 100% rename from API/media/image128.emf rename to public/media/image118.emf diff --git a/public/media/image118.png b/public/media/image118.png new file mode 100644 index 0000000000000000000000000000000000000000..8a7da9a3b7663b60432792fa1f5c8d74482d56f9 Binary files /dev/null and b/public/media/image118.png differ diff --git a/API/media/image129.emf b/public/media/image119.emf similarity index 100% rename from API/media/image129.emf rename to public/media/image119.emf diff --git a/public/media/image119.png b/public/media/image119.png new file mode 100644 index 0000000000000000000000000000000000000000..f7ce1fdedf35b2c02dd9e2dc369997e07a6439ca Binary files /dev/null and b/public/media/image119.png differ diff --git a/API/media/image12.emf b/public/media/image12.emf similarity index 100% rename from API/media/image12.emf rename to public/media/image12.emf diff --git a/public/media/image12.png b/public/media/image12.png new file mode 100644 index 0000000000000000000000000000000000000000..a3fd2ecfc01d77efad4ecf9d7f406607747a9877 Binary files /dev/null and b/public/media/image12.png differ diff --git a/API/media/image130.emf b/public/media/image120.emf similarity index 100% rename from API/media/image130.emf rename to public/media/image120.emf diff --git a/public/media/image120.png b/public/media/image120.png new file mode 100644 index 0000000000000000000000000000000000000000..ea93c993445b0cea9badb0a44cd671d40b3d50d5 Binary files /dev/null and b/public/media/image120.png differ diff --git a/API/media/image131.emf b/public/media/image121.emf similarity index 100% rename from API/media/image131.emf rename to public/media/image121.emf diff --git a/public/media/image121.png b/public/media/image121.png new file mode 100644 index 0000000000000000000000000000000000000000..e4f9f382ef1f50d128000d01877207f6695cc29b Binary files /dev/null and b/public/media/image121.png differ diff --git a/API/media/image132.emf b/public/media/image122.emf similarity index 100% rename from API/media/image132.emf rename to public/media/image122.emf diff --git a/public/media/image122.png b/public/media/image122.png new file mode 100644 index 0000000000000000000000000000000000000000..41164ba641ffd66507234cfe73e722e1714f5719 Binary files /dev/null and b/public/media/image122.png differ diff --git a/API/media/image143.emf b/public/media/image123.emf similarity index 100% rename from API/media/image143.emf rename to public/media/image123.emf diff --git a/public/media/image123.png b/public/media/image123.png new file mode 100644 index 0000000000000000000000000000000000000000..a35f99bb296159411f14815655846f3badaa5f0d Binary files /dev/null and b/public/media/image123.png differ diff --git a/API/media/image144.emf b/public/media/image124.emf similarity index 100% rename from API/media/image144.emf rename to public/media/image124.emf diff --git a/public/media/image124.png b/public/media/image124.png new file mode 100644 index 0000000000000000000000000000000000000000..8072c11c61acc5eac3436aa1467eb6c99ab9ac3f Binary files /dev/null and b/public/media/image124.png differ diff --git a/API/media/image145.emf b/public/media/image125.emf similarity index 100% rename from API/media/image145.emf rename to public/media/image125.emf diff --git a/public/media/image125.png b/public/media/image125.png new file mode 100644 index 0000000000000000000000000000000000000000..4d931467e6e7aa0b44261a90a293fe9305140e86 Binary files /dev/null and b/public/media/image125.png differ diff --git a/API/media/image146.emf b/public/media/image126.emf similarity index 100% rename from API/media/image146.emf rename to public/media/image126.emf diff --git a/public/media/image126.png b/public/media/image126.png new file mode 100644 index 0000000000000000000000000000000000000000..fae564ea4a69a192b0129a87ada4f49582042a26 Binary files /dev/null and b/public/media/image126.png differ diff --git a/API/media/image147.emf b/public/media/image127.emf similarity index 100% rename from API/media/image147.emf rename to public/media/image127.emf diff --git a/public/media/image127.png b/public/media/image127.png new file mode 100644 index 0000000000000000000000000000000000000000..e7163c3cd58a3e6cb92c0b17456473a7b29ab80c Binary files /dev/null and b/public/media/image127.png differ diff --git a/API/media/image148.png b/public/media/image128.png similarity index 100% rename from API/media/image148.png rename to public/media/image128.png diff --git a/API/media/image13.png b/public/media/image13.png similarity index 100% rename from API/media/image13.png rename to public/media/image13.png diff --git a/API/media/image14.png b/public/media/image14.png similarity index 100% rename from API/media/image14.png rename to public/media/image14.png diff --git a/API/media/image15.png b/public/media/image15.png similarity index 100% rename from API/media/image15.png rename to public/media/image15.png diff --git a/public/media/image16.emf b/public/media/image16.emf new file mode 100644 index 0000000000000000000000000000000000000000..dc28ff806e4488536b45c344151be91edd59501d Binary files /dev/null and b/public/media/image16.emf differ diff --git a/public/media/image16.png b/public/media/image16.png new file mode 100644 index 0000000000000000000000000000000000000000..6722b1725eed05c81919775125d9a5231785e042 Binary files /dev/null and b/public/media/image16.png differ diff --git a/API/media/image17.emf b/public/media/image17.emf similarity index 100% rename from API/media/image17.emf rename to public/media/image17.emf diff --git a/public/media/image17.png b/public/media/image17.png new file mode 100644 index 0000000000000000000000000000000000000000..21b3e90a56e54075309082081b26f6c0aff9e772 Binary files /dev/null and b/public/media/image17.png differ diff --git a/API/media/image18.emf b/public/media/image18.emf similarity index 100% rename from API/media/image18.emf rename to public/media/image18.emf diff --git a/public/media/image18.png b/public/media/image18.png new file mode 100644 index 0000000000000000000000000000000000000000..9bbeebe1319d11344c82cfa7ff6a7cd6110df014 Binary files /dev/null and b/public/media/image18.png differ diff --git a/API/media/image19.emf b/public/media/image19.emf similarity index 100% rename from API/media/image19.emf rename to public/media/image19.emf diff --git a/public/media/image19.png b/public/media/image19.png new file mode 100644 index 0000000000000000000000000000000000000000..592e1c49affb2256729b358f83b5dfd24abb72a6 Binary files /dev/null and b/public/media/image19.png differ diff --git a/API/media/image2.emf b/public/media/image2.emf similarity index 100% rename from API/media/image2.emf rename to public/media/image2.emf diff --git a/public/media/image2.png b/public/media/image2.png new file mode 100644 index 0000000000000000000000000000000000000000..68e137e613be433ff373231fbea0c9dab65b56fc Binary files /dev/null and b/public/media/image2.png differ diff --git a/API/media/image20.emf b/public/media/image20.emf similarity index 100% rename from API/media/image20.emf rename to public/media/image20.emf diff --git a/public/media/image20.png b/public/media/image20.png new file mode 100644 index 0000000000000000000000000000000000000000..a037a2377f01b61e75bf2ead9e1c79e5afb163d7 Binary files /dev/null and b/public/media/image20.png differ diff --git a/API/media/image21.emf b/public/media/image21.emf similarity index 100% rename from API/media/image21.emf rename to public/media/image21.emf diff --git a/public/media/image21.png b/public/media/image21.png new file mode 100644 index 0000000000000000000000000000000000000000..0b776eda5d10e0d3cf0087b5702c164c32f0a123 Binary files /dev/null and b/public/media/image21.png differ diff --git a/API/media/image22.emf b/public/media/image22.emf similarity index 100% rename from API/media/image22.emf rename to public/media/image22.emf diff --git a/public/media/image22.png b/public/media/image22.png new file mode 100644 index 0000000000000000000000000000000000000000..1489c9316e7078101288c55830e96dfa71e23b67 Binary files /dev/null and b/public/media/image22.png differ diff --git a/API/media/image23.emf b/public/media/image23.emf similarity index 100% rename from API/media/image23.emf rename to public/media/image23.emf diff --git a/public/media/image23.png b/public/media/image23.png new file mode 100644 index 0000000000000000000000000000000000000000..ffbee9280e8456f1d90d9941bb35254fc02b8c4a Binary files /dev/null and b/public/media/image23.png differ diff --git a/API/media/image24.emf b/public/media/image24.emf similarity index 100% rename from API/media/image24.emf rename to public/media/image24.emf diff --git a/public/media/image24.png b/public/media/image24.png new file mode 100644 index 0000000000000000000000000000000000000000..3a71d4af3f1f4418e802a4500583f69202c9bd49 Binary files /dev/null and b/public/media/image24.png differ diff --git a/API/media/image25.emf b/public/media/image25.emf similarity index 100% rename from API/media/image25.emf rename to public/media/image25.emf diff --git a/public/media/image25.png b/public/media/image25.png new file mode 100644 index 0000000000000000000000000000000000000000..fab322af92e410de2c30985527c526386c4a9938 Binary files /dev/null and b/public/media/image25.png differ diff --git a/public/media/image26.emf b/public/media/image26.emf new file mode 100644 index 0000000000000000000000000000000000000000..8bf95c1392fe8b8e6183356cfbab5196b9647473 Binary files /dev/null and b/public/media/image26.emf differ diff --git a/public/media/image26.png b/public/media/image26.png new file mode 100644 index 0000000000000000000000000000000000000000..8e15cfa7c58262e5f5443101239e11585413315b Binary files /dev/null and b/public/media/image26.png differ diff --git a/API/media/image27.emf b/public/media/image27.emf similarity index 100% rename from API/media/image27.emf rename to public/media/image27.emf diff --git a/public/media/image27.png b/public/media/image27.png new file mode 100644 index 0000000000000000000000000000000000000000..5e13e0147c9fc9148fc3688d25595771a43cbef6 Binary files /dev/null and b/public/media/image27.png differ diff --git a/API/media/image28.emf b/public/media/image28.emf similarity index 100% rename from API/media/image28.emf rename to public/media/image28.emf diff --git a/public/media/image28.png b/public/media/image28.png new file mode 100644 index 0000000000000000000000000000000000000000..df64c22e90ced67ad4227708830d8075cd14fe95 Binary files /dev/null and b/public/media/image28.png differ diff --git a/API/media/image29.emf b/public/media/image29.emf similarity index 100% rename from API/media/image29.emf rename to public/media/image29.emf diff --git a/public/media/image29.png b/public/media/image29.png new file mode 100644 index 0000000000000000000000000000000000000000..374b666e92efc651baa01c935bbe524fea9eafb3 Binary files /dev/null and b/public/media/image29.png differ diff --git a/API/media/image3.emf b/public/media/image3.emf similarity index 100% rename from API/media/image3.emf rename to public/media/image3.emf diff --git a/public/media/image3.png b/public/media/image3.png new file mode 100644 index 0000000000000000000000000000000000000000..79a908b194963579866fdceb034f6378d46687e3 Binary files /dev/null and b/public/media/image3.png differ diff --git a/API/media/image30.emf b/public/media/image30.emf similarity index 100% rename from API/media/image30.emf rename to public/media/image30.emf diff --git a/public/media/image30.png b/public/media/image30.png new file mode 100644 index 0000000000000000000000000000000000000000..900a66f9bc02f9f62fdfc393aa914e5f76e47d54 Binary files /dev/null and b/public/media/image30.png differ diff --git a/API/media/image31.emf b/public/media/image31.emf similarity index 100% rename from API/media/image31.emf rename to public/media/image31.emf diff --git a/public/media/image31.png b/public/media/image31.png new file mode 100644 index 0000000000000000000000000000000000000000..c8c01d6d58f8707b470f6a50a849dcb3ebc5f470 Binary files /dev/null and b/public/media/image31.png differ diff --git a/API/media/image32.emf b/public/media/image32.emf similarity index 100% rename from API/media/image32.emf rename to public/media/image32.emf diff --git a/public/media/image32.png b/public/media/image32.png new file mode 100644 index 0000000000000000000000000000000000000000..43a336ed89674f2888a12656f69dcbad52994e9a Binary files /dev/null and b/public/media/image32.png differ diff --git a/API/media/image33.emf b/public/media/image33.emf similarity index 100% rename from API/media/image33.emf rename to public/media/image33.emf diff --git a/public/media/image33.png b/public/media/image33.png new file mode 100644 index 0000000000000000000000000000000000000000..77eac56b2fcdc11cb9db96938faf339a1ce821ad Binary files /dev/null and b/public/media/image33.png differ diff --git a/API/media/image34.emf b/public/media/image34.emf similarity index 100% rename from API/media/image34.emf rename to public/media/image34.emf diff --git a/public/media/image34.png b/public/media/image34.png new file mode 100644 index 0000000000000000000000000000000000000000..5e0641b1777f5b7398d3622ade2c04f37301091e Binary files /dev/null and b/public/media/image34.png differ diff --git a/API/media/image35.emf b/public/media/image35.emf similarity index 100% rename from API/media/image35.emf rename to public/media/image35.emf diff --git a/public/media/image35.png b/public/media/image35.png new file mode 100644 index 0000000000000000000000000000000000000000..78f3031374f7429fa28f3d4dfc359023f8b1fd7c Binary files /dev/null and b/public/media/image35.png differ diff --git a/API/media/image37.emf b/public/media/image36.emf similarity index 100% rename from API/media/image37.emf rename to public/media/image36.emf diff --git a/public/media/image36.png b/public/media/image36.png new file mode 100644 index 0000000000000000000000000000000000000000..002ea48fe2847b88b58b7aeed118666362637f0c Binary files /dev/null and b/public/media/image36.png differ diff --git a/API/media/image38.emf b/public/media/image37.emf similarity index 100% rename from API/media/image38.emf rename to public/media/image37.emf diff --git a/public/media/image37.png b/public/media/image37.png new file mode 100644 index 0000000000000000000000000000000000000000..acc7730f1669d987f357fa470a22e93ab5deda51 Binary files /dev/null and b/public/media/image37.png differ diff --git a/API/media/image39.emf b/public/media/image38.emf similarity index 100% rename from API/media/image39.emf rename to public/media/image38.emf diff --git a/public/media/image38.png b/public/media/image38.png new file mode 100644 index 0000000000000000000000000000000000000000..32c5afa6a9cc142ca2d9dfa82e982541341cab53 Binary files /dev/null and b/public/media/image38.png differ diff --git a/API/media/image40.emf b/public/media/image39.emf similarity index 100% rename from API/media/image40.emf rename to public/media/image39.emf diff --git a/public/media/image39.png b/public/media/image39.png new file mode 100644 index 0000000000000000000000000000000000000000..b8ed3ed4715e39556b544296f00495f563519a35 Binary files /dev/null and b/public/media/image39.png differ diff --git a/API/media/image4.png b/public/media/image4.png similarity index 100% rename from API/media/image4.png rename to public/media/image4.png diff --git a/API/media/image41.emf b/public/media/image40.emf similarity index 100% rename from API/media/image41.emf rename to public/media/image40.emf diff --git a/public/media/image40.png b/public/media/image40.png new file mode 100644 index 0000000000000000000000000000000000000000..1a85318a91e97772d406290fe30b02d244df8664 Binary files /dev/null and b/public/media/image40.png differ diff --git a/API/media/image42.emf b/public/media/image41.emf similarity index 100% rename from API/media/image42.emf rename to public/media/image41.emf diff --git a/public/media/image41.png b/public/media/image41.png new file mode 100644 index 0000000000000000000000000000000000000000..38fb83554336884a4b2146f7da319e43f87f4382 Binary files /dev/null and b/public/media/image41.png differ diff --git a/API/media/image43.emf b/public/media/image42.emf similarity index 100% rename from API/media/image43.emf rename to public/media/image42.emf diff --git a/public/media/image42.png b/public/media/image42.png new file mode 100644 index 0000000000000000000000000000000000000000..a511a532867d927aabc5e44c7496ebb4acd05761 Binary files /dev/null and b/public/media/image42.png differ diff --git a/API/media/image44.emf b/public/media/image43.emf similarity index 100% rename from API/media/image44.emf rename to public/media/image43.emf diff --git a/public/media/image43.png b/public/media/image43.png new file mode 100644 index 0000000000000000000000000000000000000000..86510594f235f20e7ecc66cfe3b719d9eed594f3 Binary files /dev/null and b/public/media/image43.png differ diff --git a/API/media/image45.emf b/public/media/image44.emf similarity index 100% rename from API/media/image45.emf rename to public/media/image44.emf diff --git a/public/media/image44.png b/public/media/image44.png new file mode 100644 index 0000000000000000000000000000000000000000..25ad7576085ede8fa3dbbe52ce820c6b4bc6b7a1 Binary files /dev/null and b/public/media/image44.png differ diff --git a/API/media/image46.emf b/public/media/image45.emf similarity index 100% rename from API/media/image46.emf rename to public/media/image45.emf diff --git a/public/media/image45.png b/public/media/image45.png new file mode 100644 index 0000000000000000000000000000000000000000..6ea3074c80e821b0e3cfbc29f73a9753f403e050 Binary files /dev/null and b/public/media/image45.png differ diff --git a/API/media/image47.emf b/public/media/image46.emf similarity index 100% rename from API/media/image47.emf rename to public/media/image46.emf diff --git a/public/media/image46.png b/public/media/image46.png new file mode 100644 index 0000000000000000000000000000000000000000..f8c2575513153bd057090a0ba71170f9cfe3cda8 Binary files /dev/null and b/public/media/image46.png differ diff --git a/API/media/image48.emf b/public/media/image47.emf similarity index 100% rename from API/media/image48.emf rename to public/media/image47.emf diff --git a/public/media/image47.png b/public/media/image47.png new file mode 100644 index 0000000000000000000000000000000000000000..ad0052105658a1062da32c853b67a00b9f87eb08 Binary files /dev/null and b/public/media/image47.png differ diff --git a/API/media/image49.emf b/public/media/image48.emf similarity index 100% rename from API/media/image49.emf rename to public/media/image48.emf diff --git a/public/media/image48.png b/public/media/image48.png new file mode 100644 index 0000000000000000000000000000000000000000..088245dd4a3db432f43c09618f9ff916724bc669 Binary files /dev/null and b/public/media/image48.png differ diff --git a/API/media/image50.emf b/public/media/image49.emf similarity index 100% rename from API/media/image50.emf rename to public/media/image49.emf diff --git a/public/media/image49.png b/public/media/image49.png new file mode 100644 index 0000000000000000000000000000000000000000..e591a63298cd0a9ca223a89fe7a0ac820c7c7d30 Binary files /dev/null and b/public/media/image49.png differ diff --git a/API/media/image5.png b/public/media/image5.png similarity index 100% rename from API/media/image5.png rename to public/media/image5.png diff --git a/API/media/image51.emf b/public/media/image50.emf similarity index 100% rename from API/media/image51.emf rename to public/media/image50.emf diff --git a/public/media/image50.png b/public/media/image50.png new file mode 100644 index 0000000000000000000000000000000000000000..9df8e14d2ba60ef60b614cf2207d819bb44a6260 Binary files /dev/null and b/public/media/image50.png differ diff --git a/API/media/image52.emf b/public/media/image51.emf similarity index 100% rename from API/media/image52.emf rename to public/media/image51.emf diff --git a/public/media/image51.png b/public/media/image51.png new file mode 100644 index 0000000000000000000000000000000000000000..20e1c1c982bda263c7408c5aac5f7ae24dc19f3d Binary files /dev/null and b/public/media/image51.png differ diff --git a/API/media/image53.emf b/public/media/image52.emf similarity index 100% rename from API/media/image53.emf rename to public/media/image52.emf diff --git a/public/media/image52.png b/public/media/image52.png new file mode 100644 index 0000000000000000000000000000000000000000..af564eb93abbee7467dd193b493c2514e38e710f Binary files /dev/null and b/public/media/image52.png differ diff --git a/API/media/image54.emf b/public/media/image53.emf similarity index 100% rename from API/media/image54.emf rename to public/media/image53.emf diff --git a/public/media/image53.png b/public/media/image53.png new file mode 100644 index 0000000000000000000000000000000000000000..94a6425e727a3d3a4fd8a4905c7da38ec4be7fb8 Binary files /dev/null and b/public/media/image53.png differ diff --git a/API/media/image55.emf b/public/media/image54.emf similarity index 100% rename from API/media/image55.emf rename to public/media/image54.emf diff --git a/public/media/image54.png b/public/media/image54.png new file mode 100644 index 0000000000000000000000000000000000000000..2246e4a73cbcbd96250aa58c7edd1c9ccec070e9 Binary files /dev/null and b/public/media/image54.png differ diff --git a/API/media/image56.emf b/public/media/image55.emf similarity index 100% rename from API/media/image56.emf rename to public/media/image55.emf diff --git a/public/media/image55.png b/public/media/image55.png new file mode 100644 index 0000000000000000000000000000000000000000..1cfb759b642372315a193777c1c6b4f17293e330 Binary files /dev/null and b/public/media/image55.png differ diff --git a/API/media/image57.emf b/public/media/image56.emf similarity index 100% rename from API/media/image57.emf rename to public/media/image56.emf diff --git a/public/media/image56.png b/public/media/image56.png new file mode 100644 index 0000000000000000000000000000000000000000..c3976bfa707207c6dfd0ca7de5b1c445dd0ca1a6 Binary files /dev/null and b/public/media/image56.png differ diff --git a/API/media/image58.emf b/public/media/image57.emf similarity index 100% rename from API/media/image58.emf rename to public/media/image57.emf diff --git a/public/media/image57.png b/public/media/image57.png new file mode 100644 index 0000000000000000000000000000000000000000..dfaba11f6962bbfd4d070b1b2e6d3245267730a1 Binary files /dev/null and b/public/media/image57.png differ diff --git a/API/media/image59.emf b/public/media/image58.emf similarity index 100% rename from API/media/image59.emf rename to public/media/image58.emf diff --git a/public/media/image58.png b/public/media/image58.png new file mode 100644 index 0000000000000000000000000000000000000000..6dc5649b4d6abc3e219d3e0815556de8a2f59219 Binary files /dev/null and b/public/media/image58.png differ diff --git a/API/media/image60.emf b/public/media/image59.emf similarity index 100% rename from API/media/image60.emf rename to public/media/image59.emf diff --git a/public/media/image59.png b/public/media/image59.png new file mode 100644 index 0000000000000000000000000000000000000000..a341cbcbcb571c681923beb50dcd5bf63948ebaa Binary files /dev/null and b/public/media/image59.png differ diff --git a/API/media/image6.png b/public/media/image6.png similarity index 100% rename from API/media/image6.png rename to public/media/image6.png diff --git a/API/media/image61.emf b/public/media/image60.emf similarity index 100% rename from API/media/image61.emf rename to public/media/image60.emf diff --git a/public/media/image60.png b/public/media/image60.png new file mode 100644 index 0000000000000000000000000000000000000000..0c3c655e0c627f69aef9e8ab96b8f4b929037e0b Binary files /dev/null and b/public/media/image60.png differ diff --git a/API/media/image62.emf b/public/media/image61.emf similarity index 100% rename from API/media/image62.emf rename to public/media/image61.emf diff --git a/public/media/image61.png b/public/media/image61.png new file mode 100644 index 0000000000000000000000000000000000000000..9de6915f80e06c5f45dcd660911163b9bca8312e Binary files /dev/null and b/public/media/image61.png differ diff --git a/API/media/image63.emf b/public/media/image62.emf similarity index 100% rename from API/media/image63.emf rename to public/media/image62.emf diff --git a/public/media/image62.png b/public/media/image62.png new file mode 100644 index 0000000000000000000000000000000000000000..4c1d5199e188af612a402ecb14aa1e95c936f468 Binary files /dev/null and b/public/media/image62.png differ diff --git a/API/media/image64.emf b/public/media/image63.emf similarity index 100% rename from API/media/image64.emf rename to public/media/image63.emf diff --git a/public/media/image63.png b/public/media/image63.png new file mode 100644 index 0000000000000000000000000000000000000000..dec6f41829a7889ee31097a71de669e5a0521e41 Binary files /dev/null and b/public/media/image63.png differ diff --git a/API/media/image65.emf b/public/media/image64.emf similarity index 100% rename from API/media/image65.emf rename to public/media/image64.emf diff --git a/public/media/image64.png b/public/media/image64.png new file mode 100644 index 0000000000000000000000000000000000000000..955ea95f3650bcf821735e00502299baa84c0f66 Binary files /dev/null and b/public/media/image64.png differ diff --git a/public/media/image65.emf b/public/media/image65.emf new file mode 100644 index 0000000000000000000000000000000000000000..ae35714159eeb96ff6f3f16d1f705db5c004946a Binary files /dev/null and b/public/media/image65.emf differ diff --git a/public/media/image65.png b/public/media/image65.png new file mode 100644 index 0000000000000000000000000000000000000000..75ec805a49d18effe45d47b9b7e8a4b8f4f45b9b Binary files /dev/null and b/public/media/image65.png differ diff --git a/public/media/image66.emf b/public/media/image66.emf new file mode 100644 index 0000000000000000000000000000000000000000..d8e58e6bf2d675814c6282126eca8e46d44da9e9 Binary files /dev/null and b/public/media/image66.emf differ diff --git a/public/media/image66.png b/public/media/image66.png new file mode 100644 index 0000000000000000000000000000000000000000..2b2db5f5862669108b669416f7d3477b175ee3ce Binary files /dev/null and b/public/media/image66.png differ diff --git a/API/media/image68.emf b/public/media/image67.emf similarity index 100% rename from API/media/image68.emf rename to public/media/image67.emf diff --git a/public/media/image67.png b/public/media/image67.png new file mode 100644 index 0000000000000000000000000000000000000000..63618e817641b45b6c43ca0fa02248beb8854bbe Binary files /dev/null and b/public/media/image67.png differ diff --git a/API/media/image71.emf b/public/media/image68.emf similarity index 100% rename from API/media/image71.emf rename to public/media/image68.emf diff --git a/public/media/image68.png b/public/media/image68.png new file mode 100644 index 0000000000000000000000000000000000000000..91def88604c143df1841272507ffea3785c8f0ad Binary files /dev/null and b/public/media/image68.png differ diff --git a/public/media/image69.emf b/public/media/image69.emf new file mode 100644 index 0000000000000000000000000000000000000000..c26550fc188a668cad0138ef2b01443ac03634c9 Binary files /dev/null and b/public/media/image69.emf differ diff --git a/public/media/image69.png b/public/media/image69.png new file mode 100644 index 0000000000000000000000000000000000000000..b20eac10b663a8e19e6fe82bdb12ccebb0d0c72d Binary files /dev/null and b/public/media/image69.png differ diff --git a/API/media/image7.png b/public/media/image7.png similarity index 100% rename from API/media/image7.png rename to public/media/image7.png diff --git a/API/media/image79.emf b/public/media/image70.emf similarity index 100% rename from API/media/image79.emf rename to public/media/image70.emf diff --git a/public/media/image70.png b/public/media/image70.png new file mode 100644 index 0000000000000000000000000000000000000000..9acf694667cae982171afdb28d80740996cec8f2 Binary files /dev/null and b/public/media/image70.png differ diff --git a/public/media/image71.emf b/public/media/image71.emf new file mode 100644 index 0000000000000000000000000000000000000000..756e5f8adb50036e4371a8f9db81fe7c7d3ad919 Binary files /dev/null and b/public/media/image71.emf differ diff --git a/public/media/image71.png b/public/media/image71.png new file mode 100644 index 0000000000000000000000000000000000000000..a43786470f25d8c5298df3ead3654552d0236ab8 Binary files /dev/null and b/public/media/image71.png differ diff --git a/public/media/image72.emf b/public/media/image72.emf new file mode 100644 index 0000000000000000000000000000000000000000..d2160fd6a3a942ca057b4a473c4cd9249c10dee9 Binary files /dev/null and b/public/media/image72.emf differ diff --git a/public/media/image72.png b/public/media/image72.png new file mode 100644 index 0000000000000000000000000000000000000000..6ac2fdd3a65bc503063391512d4e0f801dd5e1fb Binary files /dev/null and b/public/media/image72.png differ diff --git a/public/media/image73.emf b/public/media/image73.emf new file mode 100644 index 0000000000000000000000000000000000000000..21106f73905882db5fcde9636dc3d8628e61c8ff Binary files /dev/null and b/public/media/image73.emf differ diff --git a/public/media/image73.png b/public/media/image73.png new file mode 100644 index 0000000000000000000000000000000000000000..75bd753c4d8b4fe7b36576c11ae71305cb2447bd Binary files /dev/null and b/public/media/image73.png differ diff --git a/API/media/image84.emf b/public/media/image74.emf similarity index 100% rename from API/media/image84.emf rename to public/media/image74.emf diff --git a/public/media/image74.png b/public/media/image74.png new file mode 100644 index 0000000000000000000000000000000000000000..cab31e57dc62a29fb70aafafc2e06b6427a8937b Binary files /dev/null and b/public/media/image74.png differ diff --git a/API/media/image85.emf b/public/media/image75.emf similarity index 100% rename from API/media/image85.emf rename to public/media/image75.emf diff --git a/public/media/image75.png b/public/media/image75.png new file mode 100644 index 0000000000000000000000000000000000000000..966c368ef3363c991e6db181273c3d2522fd0b39 Binary files /dev/null and b/public/media/image75.png differ diff --git a/API/media/image86.emf b/public/media/image76.emf similarity index 100% rename from API/media/image86.emf rename to public/media/image76.emf diff --git a/public/media/image76.png b/public/media/image76.png new file mode 100644 index 0000000000000000000000000000000000000000..4be44cfb4f51c767bc75656bb8f13d8c4043625a Binary files /dev/null and b/public/media/image76.png differ diff --git a/API/media/image87.emf b/public/media/image77.emf similarity index 100% rename from API/media/image87.emf rename to public/media/image77.emf diff --git a/public/media/image77.png b/public/media/image77.png new file mode 100644 index 0000000000000000000000000000000000000000..dda501e7089eb1b9e4bb641031f23d6c5e818d95 Binary files /dev/null and b/public/media/image77.png differ diff --git a/API/media/image88.emf b/public/media/image78.emf similarity index 100% rename from API/media/image88.emf rename to public/media/image78.emf diff --git a/public/media/image78.png b/public/media/image78.png new file mode 100644 index 0000000000000000000000000000000000000000..297be11b629dcde4e5ed6393ca25b76e7102f3cc Binary files /dev/null and b/public/media/image78.png differ diff --git a/API/media/image89.emf b/public/media/image79.emf similarity index 100% rename from API/media/image89.emf rename to public/media/image79.emf diff --git a/public/media/image79.png b/public/media/image79.png new file mode 100644 index 0000000000000000000000000000000000000000..524b87bcf4b2e672d097b259f78ec13b61ac9636 Binary files /dev/null and b/public/media/image79.png differ diff --git a/API/media/image8.png b/public/media/image8.png similarity index 100% rename from API/media/image8.png rename to public/media/image8.png diff --git a/API/media/image90.emf b/public/media/image80.emf similarity index 100% rename from API/media/image90.emf rename to public/media/image80.emf diff --git a/public/media/image80.png b/public/media/image80.png new file mode 100644 index 0000000000000000000000000000000000000000..52e29c6d8650938a535f0e881609521571db0c11 Binary files /dev/null and b/public/media/image80.png differ diff --git a/API/media/image91.emf b/public/media/image81.emf similarity index 100% rename from API/media/image91.emf rename to public/media/image81.emf diff --git a/public/media/image81.png b/public/media/image81.png new file mode 100644 index 0000000000000000000000000000000000000000..00a55911b7d90a425f047feac7b8527862e86788 Binary files /dev/null and b/public/media/image81.png differ diff --git a/API/media/image92.emf b/public/media/image82.emf similarity index 100% rename from API/media/image92.emf rename to public/media/image82.emf diff --git a/public/media/image82.png b/public/media/image82.png new file mode 100644 index 0000000000000000000000000000000000000000..4c9d0b34b7b7813f78202bdb9f0de3928757adcd Binary files /dev/null and b/public/media/image82.png differ diff --git a/API/media/image93.emf b/public/media/image83.emf similarity index 100% rename from API/media/image93.emf rename to public/media/image83.emf diff --git a/public/media/image83.png b/public/media/image83.png new file mode 100644 index 0000000000000000000000000000000000000000..f0a7a661601cf4377ca9ed3fb80c7f6c489fded3 Binary files /dev/null and b/public/media/image83.png differ diff --git a/API/media/image94.emf b/public/media/image84.emf similarity index 100% rename from API/media/image94.emf rename to public/media/image84.emf diff --git a/public/media/image84.png b/public/media/image84.png new file mode 100644 index 0000000000000000000000000000000000000000..6dfab61e1ea725549963ccfdd527ef0fd9f92030 Binary files /dev/null and b/public/media/image84.png differ diff --git a/API/media/image95.emf b/public/media/image85.emf similarity index 100% rename from API/media/image95.emf rename to public/media/image85.emf diff --git a/public/media/image85.png b/public/media/image85.png new file mode 100644 index 0000000000000000000000000000000000000000..fc7cec745f2d35c1de388fad58567d2278d39fe3 Binary files /dev/null and b/public/media/image85.png differ diff --git a/API/media/image96.emf b/public/media/image86.emf similarity index 100% rename from API/media/image96.emf rename to public/media/image86.emf diff --git a/public/media/image86.png b/public/media/image86.png new file mode 100644 index 0000000000000000000000000000000000000000..65f67a603760f61b20daa9ac7a00792e1c60d735 Binary files /dev/null and b/public/media/image86.png differ diff --git a/API/media/image97.emf b/public/media/image87.emf similarity index 100% rename from API/media/image97.emf rename to public/media/image87.emf diff --git a/public/media/image87.png b/public/media/image87.png new file mode 100644 index 0000000000000000000000000000000000000000..5ba7cf21549f28b37286d20573f03f6aa07136cc Binary files /dev/null and b/public/media/image87.png differ diff --git a/API/media/image98.emf b/public/media/image88.emf similarity index 100% rename from API/media/image98.emf rename to public/media/image88.emf diff --git a/public/media/image88.png b/public/media/image88.png new file mode 100644 index 0000000000000000000000000000000000000000..ff74ae03d226849f1b6671200e58c6b34eab1312 Binary files /dev/null and b/public/media/image88.png differ diff --git a/API/media/image99.emf b/public/media/image89.emf similarity index 100% rename from API/media/image99.emf rename to public/media/image89.emf diff --git a/public/media/image89.png b/public/media/image89.png new file mode 100644 index 0000000000000000000000000000000000000000..be683fb7d2858c6fc3779fe6b597c2fa247a1761 Binary files /dev/null and b/public/media/image89.png differ diff --git a/API/media/image9.png b/public/media/image9.png similarity index 100% rename from API/media/image9.png rename to public/media/image9.png diff --git a/API/media/image100.emf b/public/media/image90.emf similarity index 100% rename from API/media/image100.emf rename to public/media/image90.emf diff --git a/public/media/image90.png b/public/media/image90.png new file mode 100644 index 0000000000000000000000000000000000000000..6ea3c7ccd294e42a6692f2bed93aa191a09d1553 Binary files /dev/null and b/public/media/image90.png differ diff --git a/API/media/image101.emf b/public/media/image91.emf similarity index 100% rename from API/media/image101.emf rename to public/media/image91.emf diff --git a/public/media/image91.png b/public/media/image91.png new file mode 100644 index 0000000000000000000000000000000000000000..72cd8d25bf6db8c65f271f4cde60cf29625475be Binary files /dev/null and b/public/media/image91.png differ diff --git a/API/media/image102.emf b/public/media/image92.emf similarity index 100% rename from API/media/image102.emf rename to public/media/image92.emf diff --git a/public/media/image92.png b/public/media/image92.png new file mode 100644 index 0000000000000000000000000000000000000000..17a7f9c53a463a5c165ef860ba775d6cc1972311 Binary files /dev/null and b/public/media/image92.png differ diff --git a/API/media/image103.emf b/public/media/image93.emf similarity index 100% rename from API/media/image103.emf rename to public/media/image93.emf diff --git a/public/media/image93.png b/public/media/image93.png new file mode 100644 index 0000000000000000000000000000000000000000..cfa1985669094ea5ed8c6f4033ded78834b50e85 Binary files /dev/null and b/public/media/image93.png differ diff --git a/API/media/image104.emf b/public/media/image94.emf similarity index 100% rename from API/media/image104.emf rename to public/media/image94.emf diff --git a/public/media/image94.png b/public/media/image94.png new file mode 100644 index 0000000000000000000000000000000000000000..86718b088e300d81492f3541ae2c23c118873bf8 Binary files /dev/null and b/public/media/image94.png differ diff --git a/API/media/image105.emf b/public/media/image95.emf similarity index 100% rename from API/media/image105.emf rename to public/media/image95.emf diff --git a/public/media/image95.png b/public/media/image95.png new file mode 100644 index 0000000000000000000000000000000000000000..6f7f005d66b521926fad0065426defbf00f52c90 Binary files /dev/null and b/public/media/image95.png differ diff --git a/API/media/image106.emf b/public/media/image96.emf similarity index 100% rename from API/media/image106.emf rename to public/media/image96.emf diff --git a/public/media/image96.png b/public/media/image96.png new file mode 100644 index 0000000000000000000000000000000000000000..fa8b3208bc4a89b28e8a1cfef81d3f64c3f737ba Binary files /dev/null and b/public/media/image96.png differ diff --git a/API/media/image107.emf b/public/media/image97.emf similarity index 100% rename from API/media/image107.emf rename to public/media/image97.emf diff --git a/public/media/image97.png b/public/media/image97.png new file mode 100644 index 0000000000000000000000000000000000000000..b0f1f4f0a82d537e4ac63f4de66212903606171b Binary files /dev/null and b/public/media/image97.png differ diff --git a/API/media/image108.emf b/public/media/image98.emf similarity index 100% rename from API/media/image108.emf rename to public/media/image98.emf diff --git a/public/media/image98.png b/public/media/image98.png new file mode 100644 index 0000000000000000000000000000000000000000..b3df690a9b3edc3791294cb1f849ca11622a0867 Binary files /dev/null and b/public/media/image98.png differ diff --git a/API/media/image109.emf b/public/media/image99.emf similarity index 100% rename from API/media/image109.emf rename to public/media/image99.emf diff --git a/public/media/image99.png b/public/media/image99.png new file mode 100644 index 0000000000000000000000000000000000000000..ceb755814366cc9af305fb12a2f908f3d60780a6 Binary files /dev/null and b/public/media/image99.png differ diff --git a/public/official/.gitkeep b/public/official/.gitkeep deleted file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/public/sitemap.json b/public/sitemap.json new file mode 100644 index 0000000000000000000000000000000000000000..9f127c6e7858c9282947cfe7d0ba58398a3ed763 --- /dev/null +++ b/public/sitemap.json @@ -0,0 +1 @@ +{"section":{"id":"","level":"0","number":null,"path":"index.html","title":""},"subsections":[{"section":{"id":"intellectual-property-rights","level":"1","number":"1","path":"1-intellectual-property-rights.html#intellectual-property-rights","title":"Intellectual Property Rights"},"subsections":[]},{"section":{"id":"foreword","level":"1","number":"2","path":"2-foreword.html#foreword","title":"Foreword"},"subsections":[]},{"section":{"id":"modal-verbs-terminology","level":"1","number":"3","path":"3-modal-verbs-terminology.html#modal-verbs-terminology","title":"Modal verbs terminology"},"subsections":[]},{"section":{"id":"executive-summary","level":"1","number":"4","path":"4-executive-summary.html#executive-summary","title":"Executive summary"},"subsections":[]},{"section":{"id":"introduction","level":"1","number":"5","path":"5-introduction.html#introduction","title":"Introduction"},"subsections":[]},{"section":{"id":"tabscope","level":"1","number":"6","path":"6-tabscope.html#tabscope","title":"1\tScope"},"subsections":[]},{"section":{"id":"tabreferences","level":"1","number":"7","path":"7-tabreferences.html#tabreferences","title":"2\tReferences"},"subsections":[{"section":{"id":"tabnormative-references","level":"2","number":"7.1","path":"7-tabreferences.html#tabnormative-references","title":"2.1\tNormative references"},"subsections":[]},{"section":{"id":"tabinformative-references","level":"2","number":"7.2","path":"7-tabreferences.html#tabinformative-references","title":"2.2\tInformative references"},"subsections":[]}]},{"section":{"id":"tabdefinition-of-terms-symbols-and-abbreviations","level":"1","number":"8","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabdefinition-of-terms-symbols-and-abbreviations","title":"3\tDefinition of terms, symbols and abbreviations"},"subsections":[{"section":{"id":"tabterms","level":"2","number":"8.1","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabterms","title":"3.1\tTerms"},"subsections":[]},{"section":{"id":"tabsymbols","level":"2","number":"8.2","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tabsymbols","title":"3.2\tSymbols"},"subsections":[]},{"section":{"id":"tababbreviations","level":"2","number":"8.3","path":"8-tabdefinition-of-terms-symbols-and-abbreviations.html#tababbreviations","title":"3.3\tAbbreviations"},"subsections":[]}]},{"section":{"id":"tabcontext-information-management-framework","level":"1","number":"9","path":"9-tabcontext-information-management-framework.html#tabcontext-information-management-framework","title":"4\tContext Information Management Framework"},"subsections":[{"section":{"id":"tabintroduction","level":"2","number":"9.1","path":"9-tabcontext-information-management-framework.html#tabintroduction","title":"4.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-information-model","level":"2","number":"9.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-information-model","title":"4.2\tNGSI-LD Information Model"},"subsections":[{"section":{"id":"tabintroduction-1","level":"3","number":"9.2.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-1","title":"4.2.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-meta-model","level":"3","number":"9.2.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-meta-model","title":"4.2.2\tNGSI-LD Meta Model"},"subsections":[]},{"section":{"id":"tabcross-domain-ontology","level":"3","number":"9.2.3","path":"9-tabcontext-information-management-framework.html#tabcross-domain-ontology","title":"4.2.3\tCross Domain Ontology"},"subsections":[]},{"section":{"id":"tabngsi-ld-domain-specific-models-and-instantiation","level":"3","number":"9.2.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-domain-specific-models-and-instantiation","title":"4.2.4\tNGSI-LD domain-specific models and instantiation"},"subsections":[]},{"section":{"id":"tabuml-representation","level":"3","number":"9.2.5","path":"9-tabcontext-information-management-framework.html#tabuml-representation","title":"4.2.5\tUML representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-architectural-considerations","level":"2","number":"9.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-architectural-considerations","title":"4.3\tNGSI-LD Architectural Considerations"},"subsections":[{"section":{"id":"tabintroduction-2","level":"3","number":"9.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-2","title":"4.3.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabcentralized-architecture","level":"3","number":"9.3.2","path":"9-tabcontext-information-management-framework.html#tabcentralized-architecture","title":"4.3.2\tCentralized architecture"},"subsections":[]},{"section":{"id":"tabdistributed-architecture","level":"3","number":"9.3.3","path":"9-tabcontext-information-management-framework.html#tabdistributed-architecture","title":"4.3.3\tDistributed architecture"},"subsections":[]},{"section":{"id":"tabfederated-architecture","level":"3","number":"9.3.4","path":"9-tabcontext-information-management-framework.html#tabfederated-architecture","title":"4.3.4\tFederated architecture"},"subsections":[]},{"section":{"id":"tabngsi-ld-api-structure-and-implementation-options","level":"3","number":"9.3.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-api-structure-and-implementation-options","title":"4.3.5\tNGSI-LD API Structure and Implementation Options"},"subsections":[]},{"section":{"id":"tabdistributed-operations","level":"3","number":"9.3.6","path":"9-tabcontext-information-management-framework.html#tabdistributed-operations","title":"4.3.6\tDistributed Operations"},"subsections":[{"section":{"id":"tabintroduction-3","level":"4","number":"9.3.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-3","title":"4.3.6.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabadditive-registrations","level":"4","number":"9.3.6.2","path":"9-tabcontext-information-management-framework.html#tabadditive-registrations","title":"4.3.6.2\tAdditive Registrations"},"subsections":[]},{"section":{"id":"tabproxied-registrations","level":"4","number":"9.3.6.3","path":"9-tabcontext-information-management-framework.html#tabproxied-registrations","title":"4.3.6.3\tProxied Registrations"},"subsections":[]},{"section":{"id":"tablimiting-cascading-distributed-operations","level":"4","number":"9.3.6.4","path":"9-tabcontext-information-management-framework.html#tablimiting-cascading-distributed-operations","title":"4.3.6.4\tLimiting Cascading Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source","level":"4","number":"9.3.6.5","path":"9-tabcontext-information-management-framework.html#tabextra-information-to-provide-when-contacting-context-source","title":"4.3.6.5\tExtra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","level":"4","number":"9.3.6.6","path":"9-tabcontext-information-management-framework.html#tabadditional-pre--and-post-processing-of-extra-information-when-contacting-context-source","title":"4.3.6.6\tAdditional pre- and post-processing of extra information when contacting Context Source"},"subsections":[]},{"section":{"id":"tabquerying-and-retrieving-distributed-entities-as-unitary-operations","level":"4","number":"9.3.6.7","path":"9-tabcontext-information-management-framework.html#tabquerying-and-retrieving-distributed-entities-as-unitary-operations","title":"4.3.6.7\tQuerying and Retrieving Distributed Entities as Unitary Operations"},"subsections":[]},{"section":{"id":"backwards-compatibility-of-context-source-payloads","level":"4","number":"9.3.6.8","path":"9-tabcontext-information-management-framework.html#backwards-compatibility-of-context-source-payloads","title":"4.3.6.8 Backwards compatibility of Context Source payloads"},"subsections":[]}]}]},{"section":{"id":"tabcore-and-user-ngsi-ld-context","level":"2","number":"9.4","path":"9-tabcontext-information-management-framework.html#tabcore-and-user-ngsi-ld-context","title":"4.4\tCore and user NGSI-LD @context"},"subsections":[]},{"section":{"id":"tabngsi-ld-data-representation","level":"2","number":"9.5","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-data-representation","title":"4.5\tNGSI-LD Data Representation"},"subsections":[{"section":{"id":"tabintroduction-4","level":"3","number":"9.5.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-4","title":"4.5.0\tIntroduction"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-representation","level":"3","number":"9.5.2","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-representation","title":"4.5.1\tNGSI-LD Entity Representation"},"subsections":[]},{"section":{"id":"tabngsi-ld-property-representations","level":"3","number":"9.5.3","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-property-representations","title":"4.5.2\tNGSI-LD Property Representations"},"subsections":[{"section":{"id":"tabintroduction-5","level":"4","number":"9.5.3.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-5","title":"4.5.2.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-property","level":"4","number":"9.5.3.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-property","title":"4.5.2.2\tNormalized NGSI-LD Property"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-property","level":"4","number":"9.5.3.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-property","title":"4.5.2.3\tConcise NGSI-LD Property"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-relationship-representations","level":"3","number":"9.5.4","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-relationship-representations","title":"4.5.3\tNGSI-LD Relationship Representations"},"subsections":[{"section":{"id":"tabintroduction-6","level":"4","number":"9.5.4.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-6","title":"4.5.3.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-relationship","level":"4","number":"9.5.4.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-relationship","title":"4.5.3.2\tNormalized NGSI-LD Relationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-relationship","level":"4","number":"9.5.4.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-relationship","title":"4.5.3.3\tConcise NGSI-LD Relationship"},"subsections":[]}]},{"section":{"id":"tabsimplified-representation","level":"3","number":"9.5.5","path":"9-tabcontext-information-management-framework.html#tabsimplified-representation","title":"4.5.4\tSimplified Representation"},"subsections":[]},{"section":{"id":"tabmulti-attribute-support","level":"3","number":"9.5.6","path":"9-tabcontext-information-management-framework.html#tabmulti-attribute-support","title":"4.5.5\tMulti-Attribute Support"},"subsections":[{"section":{"id":"tabintroduction-7","level":"4","number":"9.5.6.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-7","title":"4.5.5.1\tIntroduction"},"subsections":[]},{"section":{"id":"processing-of-conflicting-transient-entities","level":"4","number":"9.5.6.2","path":"9-tabcontext-information-management-framework.html#processing-of-conflicting-transient-entities","title":"4.5.5.2 Processing of Conflicting Transient Entities"},"subsections":[]},{"section":{"id":"processing-of-conflicting-attributes","level":"4","number":"9.5.6.3","path":"9-tabcontext-information-management-framework.html#processing-of-conflicting-attributes","title":"4.5.5.3 Processing of Conflicting Attributes"},"subsections":[]}]},{"section":{"id":"tabtemporal-representation-of-an-entity","level":"3","number":"9.5.7","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-an-entity","title":"4.5.6\tTemporal Representation of an Entity"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-property","level":"3","number":"9.5.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-property","title":"4.5.7\tTemporal Representation of a Property"},"subsections":[]},{"section":{"id":"tabtemporal-representation-of-a-relationship","level":"3","number":"9.5.9","path":"9-tabcontext-information-management-framework.html#tabtemporal-representation-of-a-relationship","title":"4.5.8\tTemporal Representation of a Relationship"},"subsections":[]},{"section":{"id":"tabsimplified-temporal-representation-of-an-entity","level":"3","number":"9.5.10","path":"9-tabcontext-information-management-framework.html#tabsimplified-temporal-representation-of-an-entity","title":"4.5.9\tSimplified temporal representation of an Entity"},"subsections":[]},{"section":{"id":"tabentity-type-list-representation","level":"3","number":"9.5.11","path":"9-tabcontext-information-management-framework.html#tabentity-type-list-representation","title":"4.5.10\tEntity Type List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-entity-type-list-representation","level":"3","number":"9.5.12","path":"9-tabcontext-information-management-framework.html#tabdetailed-entity-type-list-representation","title":"4.5.11\tDetailed Entity Type List Representation"},"subsections":[]},{"section":{"id":"tabentity-type-information-representation","level":"3","number":"9.5.13","path":"9-tabcontext-information-management-framework.html#tabentity-type-information-representation","title":"4.5.12\tEntity Type Information Representation"},"subsections":[]},{"section":{"id":"tabattribute-list-representation","level":"3","number":"9.5.14","path":"9-tabcontext-information-management-framework.html#tabattribute-list-representation","title":"4.5.13\tAttribute List Representation"},"subsections":[]},{"section":{"id":"tabdetailed-attribute-list-representation","level":"3","number":"9.5.15","path":"9-tabcontext-information-management-framework.html#tabdetailed-attribute-list-representation","title":"4.5.14\tDetailed Attribute List Representation"},"subsections":[]},{"section":{"id":"tabattribute-information-representation","level":"3","number":"9.5.16","path":"9-tabcontext-information-management-framework.html#tabattribute-information-representation","title":"4.5.15\tAttribute Information Representation"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-entities","level":"3","number":"9.5.17","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-entities","title":"4.5.16\tGeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword","level":"4","number":"9.5.17.1","path":"9-tabcontext-information-management-framework.html#tabforeword","title":"4.5.16.0\tForeword"},"subsections":[]},{"section":{"id":"tabtop-level-geometry-field-selection-algorithm","level":"4","number":"9.5.17.2","path":"9-tabcontext-information-management-framework.html#tabtop-level-geometry-field-selection-algorithm","title":"4.5.16.1\tTop-level \"geometry\" field selection algorithm"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-an-individual-entity","level":"4","number":"9.5.17.3","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-an-individual-entity","title":"4.5.16.2\tGeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-multiple-entities","level":"4","number":"9.5.17.4","path":"9-tabcontext-information-management-framework.html#tabgeojson-representation-of-multiple-entities","title":"4.5.16.3\tGeoJSON Representation of Multiple Entities"},"subsections":[]}]},{"section":{"id":"tabsimplified-geojson-representation-of-entities","level":"3","number":"9.5.18","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-entities","title":"4.5.17\tSimplified GeoJSON Representation of Entities"},"subsections":[{"section":{"id":"tabforeword-1","level":"4","number":"9.5.18.1","path":"9-tabcontext-information-management-framework.html#tabforeword-1","title":"4.5.17.0\tForeword"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-an-individual-entity","level":"4","number":"9.5.18.2","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-an-individual-entity","title":"4.5.17.1\tSimplified GeoJSON Representation of an individual Entity"},"subsections":[]},{"section":{"id":"tabsimplified-geojson-representation-of-multiple-entities","level":"4","number":"9.5.18.3","path":"9-tabcontext-information-management-framework.html#tabsimplified-geojson-representation-of-multiple-entities","title":"4.5.17.2\tSimplified GeoJSON Representation of multiple Entities"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-languageproperty-representations","level":"3","number":"9.5.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-languageproperty-representations","title":"4.5.18\tNGSI-LD LanguageProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-8","level":"4","number":"9.5.19.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-8","title":"4.5.18.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-languageproperty","level":"4","number":"9.5.19.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-languageproperty","title":"4.5.18.2\tNormalized NGSI-LD LanguageProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-languageproperty","level":"4","number":"9.5.19.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-languageproperty","title":"4.5.18.3\tConcise NGSI-LD LanguageProperty"},"subsections":[]}]},{"section":{"id":"tabaggregated-temporal-representation-of-an-entity","level":"3","number":"9.5.20","path":"9-tabcontext-information-management-framework.html#tabaggregated-temporal-representation-of-an-entity","title":"4.5.19\tAggregated temporal representation of an Entity"},"subsections":[{"section":{"id":"tabforeword-2","level":"4","number":"9.5.20.1","path":"9-tabcontext-information-management-framework.html#tabforeword-2","title":"4.5.19.0\tForeword"},"subsections":[]},{"section":{"id":"tabsupported-behaviours-for-aggregation-functions","level":"4","number":"9.5.20.2","path":"9-tabcontext-information-management-framework.html#tabsupported-behaviours-for-aggregation-functions","title":"4.5.19.1\tSupported behaviours for aggregation functions"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-vocabproperty-representations","level":"3","number":"9.5.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-vocabproperty-representations","title":"4.5.20\tNGSI-LD VocabProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-9","level":"4","number":"9.5.21.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-9","title":"4.5.20.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-vocabproperty","title":"4.5.20.2\tNormalized NGSI-LD VocabProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-vocabproperty","level":"4","number":"9.5.21.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-vocabproperty","title":"4.5.20.3\tConcise NGSI-LD VocabProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listproperty-representations","level":"3","number":"9.5.22","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listproperty-representations","title":"4.5.21\tNGSI-LD ListProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-10","level":"4","number":"9.5.22.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-10","title":"4.5.21.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listproperty","level":"4","number":"9.5.22.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listproperty","title":"4.5.21.2\tNormalized NGSI-LD ListProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listproperty","level":"4","number":"9.5.22.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listproperty","title":"4.5.21.3\tConcise NGSI-LD ListProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-listrelationship-representations","level":"3","number":"9.5.23","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-listrelationship-representations","title":"4.5.22\tNGSI-LD ListRelationship Representations"},"subsections":[{"section":{"id":"tabintroduction-11","level":"4","number":"9.5.23.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-11","title":"4.5.22.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-listrelationship","level":"4","number":"9.5.23.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-listrelationship","title":"4.5.22.2\tNormalized NGSI-LD ListRelationship"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-listrelationship","level":"4","number":"9.5.23.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-listrelationship","title":"4.5.22.3\tConcise NGSI-LD ListRelationship"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-linked-entity-retrieval","level":"3","number":"9.5.24","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-linked-entity-retrieval","title":"4.5.23\tNGSI-LD Linked Entity Retrieval"},"subsections":[{"section":{"id":"tabintroduction-12","level":"4","number":"9.5.24.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-12","title":"4.5.23.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabinline-linked-entity-representation","level":"4","number":"9.5.24.2","path":"9-tabcontext-information-management-framework.html#tabinline-linked-entity-representation","title":"4.5.23.2\tInline Linked Entity Representation"},"subsections":[]},{"section":{"id":"tabflattened-linked-entity-representation","level":"4","number":"9.5.24.3","path":"9-tabcontext-information-management-framework.html#tabflattened-linked-entity-representation","title":"4.5.23.3\tFlattened Linked Entity Representation"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-jsonproperty-representations","level":"3","number":"9.5.25","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-jsonproperty-representations","title":"4.5.24\tNGSI-LD JsonProperty Representations"},"subsections":[{"section":{"id":"tabintroduction-13","level":"4","number":"9.5.25.1","path":"9-tabcontext-information-management-framework.html#tabintroduction-13","title":"4.5.24.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnormalized-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.2","path":"9-tabcontext-information-management-framework.html#tabnormalized-ngsi-ld-jsonproperty","title":"4.5.24.2\tNormalized NGSI-LD JsonProperty"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-jsonproperty","level":"4","number":"9.5.25.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-jsonproperty","title":"4.5.24.3\tConcise NGSI-LD JsonProperty"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-entitymap-representation","level":"3","number":"9.5.26","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entitymap-representation","title":"4.5.25\tNGSI-LD EntityMap Representation"},"subsections":[]}]},{"section":{"id":"tabdata-representation-restrictions","level":"2","number":"9.6","path":"9-tabcontext-information-management-framework.html#tabdata-representation-restrictions","title":"4.6\tData Representation Restrictions"},"subsections":[{"section":{"id":"tabsupported-text-encodings","level":"3","number":"9.6.1","path":"9-tabcontext-information-management-framework.html#tabsupported-text-encodings","title":"4.6.1\tSupported text encodings"},"subsections":[]},{"section":{"id":"tabsupported-names","level":"3","number":"9.6.2","path":"9-tabcontext-information-management-framework.html#tabsupported-names","title":"4.6.2\tSupported names"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-values","level":"3","number":"9.6.3","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-values","title":"4.6.3\tSupported data types for Values"},"subsections":[]},{"section":{"id":"tabsupported-content","level":"3","number":"9.6.4","path":"9-tabcontext-information-management-framework.html#tabsupported-content","title":"4.6.4\tSupported Content"},"subsections":[]},{"section":{"id":"tabsupported-data-types-for-languagemaps","level":"3","number":"9.6.5","path":"9-tabcontext-information-management-framework.html#tabsupported-data-types-for-languagemaps","title":"4.6.5\tSupported data types for LanguageMaps"},"subsections":[]},{"section":{"id":"tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","level":"3","number":"9.6.6","path":"9-tabcontext-information-management-framework.html#tabordering-of-entities-in-arrays-having-more-than-one-instance-of-the-same-entity","title":"4.6.6\tOrdering of Entities in arrays having more than one instance of the same Entity"},"subsections":[]}]},{"section":{"id":"tabgeospatial-properties","level":"2","number":"9.7","path":"9-tabcontext-information-management-framework.html#tabgeospatial-properties","title":"4.7\tGeospatial Properties"},"subsections":[{"section":{"id":"tabgeojson-geometries","level":"3","number":"9.7.1","path":"9-tabcontext-information-management-framework.html#tabgeojson-geometries","title":"4.7.1\tGeoJSON Geometries"},"subsections":[]},{"section":{"id":"tabrepresentation-of-geojson-geometries-in-json-ld","level":"3","number":"9.7.2","path":"9-tabcontext-information-management-framework.html#tabrepresentation-of-geojson-geometries-in-json-ld","title":"4.7.2\tRepresentation of GeoJSON Geometries in JSON-LD"},"subsections":[]},{"section":{"id":"tabconcise-ngsi-ld-geoproperty","level":"3","number":"9.7.3","path":"9-tabcontext-information-management-framework.html#tabconcise-ngsi-ld-geoproperty","title":"4.7.3\tConcise NGSI-LD GeoProperty"},"subsections":[]}]},{"section":{"id":"tabtemporal-properties","level":"2","number":"9.8","path":"9-tabcontext-information-management-framework.html#tabtemporal-properties","title":"4.8\tTemporal Properties"},"subsections":[]},{"section":{"id":"tabngsi-ld-query-language","level":"2","number":"9.9","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-query-language","title":"4.9\tNGSI-LD Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-geoquery-language","level":"2","number":"9.10","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-geoquery-language","title":"4.10\tNGSI-LD Geoquery Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-temporal-query-language","level":"2","number":"9.11","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-temporal-query-language","title":"4.11\tNGSI-LD Temporal Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-pagination","level":"2","number":"9.12","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-pagination","title":"4.12\tNGSI-LD Pagination"},"subsections":[]},{"section":{"id":"tabcounting-the-number-of-results","level":"2","number":"9.13","path":"9-tabcontext-information-management-framework.html#tabcounting-the-number-of-results","title":"4.13\tCounting the Number of Results"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-tenants","level":"2","number":"9.14","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-tenants","title":"4.14\tSupporting Multiple Tenants"},"subsections":[]},{"section":{"id":"tabngsi-ld-language-filter","level":"2","number":"9.15","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-language-filter","title":"4.15\tNGSI-LD Language Filter"},"subsections":[]},{"section":{"id":"tabsupporting-multiple-entity-types","level":"2","number":"9.16","path":"9-tabcontext-information-management-framework.html#tabsupporting-multiple-entity-types","title":"4.16\tSupporting Multiple Entity Types"},"subsections":[]},{"section":{"id":"tabngsi-ld-entity-type-selection-language","level":"2","number":"9.17","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-entity-type-selection-language","title":"4.17\tNGSI-LD Entity Type Selection Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-scopes","level":"2","number":"9.18","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scopes","title":"4.18\tNGSI-LD Scopes"},"subsections":[]},{"section":{"id":"tabngsi-ld-scope-query-language","level":"2","number":"9.19","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-scope-query-language","title":"4.19\tNGSI-LD Scope Query Language"},"subsections":[]},{"section":{"id":"tabngsi-ld-distributed-operation-names","level":"2","number":"9.20","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-distributed-operation-names","title":"4.20\tNGSI-LD Distributed Operation names"},"subsections":[]},{"section":{"id":"tabngsi-ld-attribute-projection-language","level":"2","number":"9.21","path":"9-tabcontext-information-management-framework.html#tabngsi-ld-attribute-projection-language","title":"4.21\tNGSI-LD Attribute Projection Language"},"subsections":[]},{"section":{"id":"transient-storage-of-entities-and-attributes","level":"2","number":"9.22","path":"9-tabcontext-information-management-framework.html#transient-storage-of-entities-and-attributes","title":"4.22 Transient Storage of Entities and Attributes"},"subsections":[]}]},{"section":{"id":"tabapi-operation-definition","level":"1","number":"10","path":"10-tabapi-operation-definition.html#tabapi-operation-definition","title":"5\tAPI Operation Definition"},"subsections":[{"section":{"id":"tabintroduction-14","level":"2","number":"10.1","path":"10-tabapi-operation-definition.html#tabintroduction-14","title":"5.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabdata-types","level":"2","number":"10.2","path":"10-tabapi-operation-definition.html#tabdata-types","title":"5.2\tData Types"},"subsections":[{"section":{"id":"tabintroduction-15","level":"3","number":"10.2.1","path":"10-tabapi-operation-definition.html#tabintroduction-15","title":"5.2.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabcommon-members","level":"3","number":"10.2.2","path":"10-tabapi-operation-definition.html#tabcommon-members","title":"5.2.2\tCommon members"},"subsections":[]},{"section":{"id":"tabcontext","level":"3","number":"10.2.3","path":"10-tabapi-operation-definition.html#tabcontext","title":"5.2.3\t@context"},"subsections":[]},{"section":{"id":"tabentity","level":"3","number":"10.2.4","path":"10-tabapi-operation-definition.html#tabentity","title":"5.2.4\tEntity"},"subsections":[]},{"section":{"id":"tabproperty","level":"3","number":"10.2.5","path":"10-tabapi-operation-definition.html#tabproperty","title":"5.2.5\tProperty"},"subsections":[]},{"section":{"id":"tabrelationship","level":"3","number":"10.2.6","path":"10-tabapi-operation-definition.html#tabrelationship","title":"5.2.6\tRelationship"},"subsections":[]},{"section":{"id":"tabgeoproperty","level":"3","number":"10.2.7","path":"10-tabapi-operation-definition.html#tabgeoproperty","title":"5.2.7\tGeoProperty"},"subsections":[]},{"section":{"id":"tabentityinfo","level":"3","number":"10.2.8","path":"10-tabapi-operation-definition.html#tabentityinfo","title":"5.2.8\tEntityInfo"},"subsections":[]},{"section":{"id":"tabcsourceregistration","level":"3","number":"10.2.9","path":"10-tabapi-operation-definition.html#tabcsourceregistration","title":"5.2.9\tCSourceRegistration"},"subsections":[]},{"section":{"id":"tabregistrationinfo","level":"3","number":"10.2.10","path":"10-tabapi-operation-definition.html#tabregistrationinfo","title":"5.2.10\tRegistrationInfo"},"subsections":[]},{"section":{"id":"tabtimeinterval","level":"3","number":"10.2.11","path":"10-tabapi-operation-definition.html#tabtimeinterval","title":"5.2.11\tTimeInterval"},"subsections":[]},{"section":{"id":"tabsubscription","level":"3","number":"10.2.12","path":"10-tabapi-operation-definition.html#tabsubscription","title":"5.2.12\tSubscription"},"subsections":[]},{"section":{"id":"tabgeoquery","level":"3","number":"10.2.13","path":"10-tabapi-operation-definition.html#tabgeoquery","title":"5.2.13\tGeoQuery"},"subsections":[]},{"section":{"id":"tabnotificationparams","level":"3","number":"10.2.14","path":"10-tabapi-operation-definition.html#tabnotificationparams","title":"5.2.14\tNotificationParams"},"subsections":[{"section":{"id":"tabnotificationparams-data-type-definition","level":"4","number":"10.2.14.1","path":"10-tabapi-operation-definition.html#tabnotificationparams-data-type-definition","title":"5.2.14.1\tNotificationParams data type definition"},"subsections":[]},{"section":{"id":"taboutput-only-members","level":"4","number":"10.2.14.2","path":"10-tabapi-operation-definition.html#taboutput-only-members","title":"5.2.14.2\tOutput only members"},"subsections":[]}]},{"section":{"id":"tabendpoint","level":"3","number":"10.2.15","path":"10-tabapi-operation-definition.html#tabendpoint","title":"5.2.15\tEndpoint"},"subsections":[]},{"section":{"id":"tabbatchoperationresult","level":"3","number":"10.2.16","path":"10-tabapi-operation-definition.html#tabbatchoperationresult","title":"5.2.16\tBatchOperationResult"},"subsections":[]},{"section":{"id":"tabbatchentityerror","level":"3","number":"10.2.17","path":"10-tabapi-operation-definition.html#tabbatchentityerror","title":"5.2.17\tBatchEntityError"},"subsections":[]},{"section":{"id":"tabupdateresult","level":"3","number":"10.2.18","path":"10-tabapi-operation-definition.html#tabupdateresult","title":"5.2.18\tUpdateResult"},"subsections":[]},{"section":{"id":"tabnotupdateddetails","level":"3","number":"10.2.19","path":"10-tabapi-operation-definition.html#tabnotupdateddetails","title":"5.2.19\tNotUpdatedDetails"},"subsections":[]},{"section":{"id":"tabentitytemporal","level":"3","number":"10.2.20","path":"10-tabapi-operation-definition.html#tabentitytemporal","title":"5.2.20\tEntityTemporal"},"subsections":[]},{"section":{"id":"tabtemporalquery","level":"3","number":"10.2.21","path":"10-tabapi-operation-definition.html#tabtemporalquery","title":"5.2.21\tTemporalQuery"},"subsections":[]},{"section":{"id":"tabkeyvaluepair","level":"3","number":"10.2.22","path":"10-tabapi-operation-definition.html#tabkeyvaluepair","title":"5.2.22\tKeyValuePair"},"subsections":[]},{"section":{"id":"tabquery","level":"3","number":"10.2.23","path":"10-tabapi-operation-definition.html#tabquery","title":"5.2.23\tQuery"},"subsections":[]},{"section":{"id":"tabentitytypelist","level":"3","number":"10.2.24","path":"10-tabapi-operation-definition.html#tabentitytypelist","title":"5.2.24\tEntityTypeList"},"subsections":[]},{"section":{"id":"tabentitytype","level":"3","number":"10.2.25","path":"10-tabapi-operation-definition.html#tabentitytype","title":"5.2.25\tEntityType"},"subsections":[]},{"section":{"id":"tabentitytypeinfo","level":"3","number":"10.2.26","path":"10-tabapi-operation-definition.html#tabentitytypeinfo","title":"5.2.26\tEntityTypeInfo"},"subsections":[]},{"section":{"id":"tabattributelist","level":"3","number":"10.2.27","path":"10-tabapi-operation-definition.html#tabattributelist","title":"5.2.27\tAttributeList"},"subsections":[]},{"section":{"id":"tabattribute","level":"3","number":"10.2.28","path":"10-tabapi-operation-definition.html#tabattribute","title":"5.2.28\tAttribute"},"subsections":[]},{"section":{"id":"tabfeature","level":"3","number":"10.2.29","path":"10-tabapi-operation-definition.html#tabfeature","title":"5.2.29\tFeature"},"subsections":[]},{"section":{"id":"tabfeaturecollection","level":"3","number":"10.2.30","path":"10-tabapi-operation-definition.html#tabfeaturecollection","title":"5.2.30\tFeatureCollection"},"subsections":[]},{"section":{"id":"tabfeatureproperties","level":"3","number":"10.2.31","path":"10-tabapi-operation-definition.html#tabfeatureproperties","title":"5.2.31\tFeatureProperties"},"subsections":[]},{"section":{"id":"tablanguageproperty","level":"3","number":"10.2.32","path":"10-tabapi-operation-definition.html#tablanguageproperty","title":"5.2.32\tLanguageProperty"},"subsections":[]},{"section":{"id":"tabentityselector","level":"3","number":"10.2.33","path":"10-tabapi-operation-definition.html#tabentityselector","title":"5.2.33\tEntitySelector"},"subsections":[]},{"section":{"id":"tabregistrationmanagementinfo","level":"3","number":"10.2.34","path":"10-tabapi-operation-definition.html#tabregistrationmanagementinfo","title":"5.2.34\tRegistrationManagementInfo"},"subsections":[]},{"section":{"id":"tabvocabproperty","level":"3","number":"10.2.35","path":"10-tabapi-operation-definition.html#tabvocabproperty","title":"5.2.35\tVocabProperty"},"subsections":[]},{"section":{"id":"tablistproperty","level":"3","number":"10.2.36","path":"10-tabapi-operation-definition.html#tablistproperty","title":"5.2.36\tListProperty"},"subsections":[]},{"section":{"id":"tablistrelationship","level":"3","number":"10.2.37","path":"10-tabapi-operation-definition.html#tablistrelationship","title":"5.2.37\tListRelationship"},"subsections":[]},{"section":{"id":"tabjsonproperty","level":"3","number":"10.2.38","path":"10-tabapi-operation-definition.html#tabjsonproperty","title":"5.2.38\tJsonProperty"},"subsections":[]},{"section":{"id":"tabentitymap","level":"3","number":"10.2.39","path":"10-tabapi-operation-definition.html#tabentitymap","title":"5.2.39\tEntityMap"},"subsections":[]},{"section":{"id":"tabcontext-source-identity","level":"3","number":"10.2.40","path":"10-tabapi-operation-definition.html#tabcontext-source-identity","title":"5.2.40\tContext Source Identity"},"subsections":[]}]},{"section":{"id":"tabnotification-data-types","level":"2","number":"10.3","path":"10-tabapi-operation-definition.html#tabnotification-data-types","title":"5.3\tNotification data types"},"subsections":[{"section":{"id":"tabnotification","level":"3","number":"10.3.1","path":"10-tabapi-operation-definition.html#tabnotification","title":"5.3.1\tNotification"},"subsections":[]},{"section":{"id":"tabcsourcenotification","level":"3","number":"10.3.2","path":"10-tabapi-operation-definition.html#tabcsourcenotification","title":"5.3.2\tCSourceNotification"},"subsections":[]},{"section":{"id":"tabtriggerreasonenumeration","level":"3","number":"10.3.3","path":"10-tabapi-operation-definition.html#tabtriggerreasonenumeration","title":"5.3.3\tTriggerReasonEnumeration"},"subsections":[]}]},{"section":{"id":"tabngsi-ld-fragments","level":"2","number":"10.4","path":"10-tabapi-operation-definition.html#tabngsi-ld-fragments","title":"5.4\tNGSI-LD Fragments"},"subsections":[]},{"section":{"id":"tabcommon-behaviours","level":"2","number":"10.5","path":"10-tabapi-operation-definition.html#tabcommon-behaviours","title":"5.5\tCommon Behaviours"},"subsections":[{"section":{"id":"tabintroduction-16","level":"3","number":"10.5.1","path":"10-tabapi-operation-definition.html#tabintroduction-16","title":"5.5.1\tIntroduction"},"subsections":[]},{"section":{"id":"taberror-types","level":"3","number":"10.5.2","path":"10-tabapi-operation-definition.html#taberror-types","title":"5.5.2\tError types"},"subsections":[]},{"section":{"id":"taberror-response-payload-body","level":"3","number":"10.5.3","path":"10-tabapi-operation-definition.html#taberror-response-payload-body","title":"5.5.3\tError response payload body"},"subsections":[]},{"section":{"id":"tabgeneral-ngsi-ld-validation","level":"3","number":"10.5.4","path":"10-tabapi-operation-definition.html#tabgeneral-ngsi-ld-validation","title":"5.5.4\tGeneral NGSI-LD validation"},"subsections":[]},{"section":{"id":"tabdefault-context-assignment","level":"3","number":"10.5.5","path":"10-tabapi-operation-definition.html#tabdefault-context-assignment","title":"5.5.5\tDefault @context assignment"},"subsections":[]},{"section":{"id":"taboperation-execution-and-generic-error-handling","level":"3","number":"10.5.6","path":"10-tabapi-operation-definition.html#taboperation-execution-and-generic-error-handling","title":"5.5.6\tOperation execution and generic error handling"},"subsections":[]},{"section":{"id":"tabterm-to-uri-expansion-or-compaction","level":"3","number":"10.5.7","path":"10-tabapi-operation-definition.html#tabterm-to-uri-expansion-or-compaction","title":"5.5.7\tTerm to URI expansion or compaction"},"subsections":[]},{"section":{"id":"tabpartial-update-patch-behaviour","level":"3","number":"10.5.8","path":"10-tabapi-operation-definition.html#tabpartial-update-patch-behaviour","title":"5.5.8\tPartial Update Patch Behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour","level":"3","number":"10.5.9","path":"10-tabapi-operation-definition.html#tabpagination-behaviour","title":"5.5.9\tPagination Behaviour"},"subsections":[]},{"section":{"id":"tabmulti-tenant-behaviour","level":"3","number":"10.5.10","path":"10-tabapi-operation-definition.html#tabmulti-tenant-behaviour","title":"5.5.10\tMulti-Tenant Behaviour"},"subsections":[]},{"section":{"id":"tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","level":"3","number":"10.5.11","path":"10-tabapi-operation-definition.html#tabmore-than-one-instance-of-the-same-entity-in-an-entity-array","title":"5.5.11\tMore than one instance of the same Entity in an Entity array"},"subsections":[{"section":{"id":"tabforeword-3","level":"4","number":"10.5.11.1","path":"10-tabapi-operation-definition.html#tabforeword-3","title":"5.5.11.0\tForeword"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-case","level":"4","number":"10.5.11.2","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-case","title":"5.5.11.1\tBatch Entity Creation case"},"subsections":[]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert-case","level":"4","number":"10.5.11.3","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert-case","title":"5.5.11.2\tBatch Entity Creation or Update (Upsert) case"},"subsections":[]},{"section":{"id":"tabbatch-entity-update-case","level":"4","number":"10.5.11.4","path":"10-tabapi-operation-definition.html#tabbatch-entity-update-case","title":"5.5.11.3\tBatch Entity Update case"},"subsections":[]},{"section":{"id":"tabbatch-entity-delete-case","level":"4","number":"10.5.11.5","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete-case","title":"5.5.11.4\tBatch Entity Delete case"},"subsections":[]},{"section":{"id":"tabbatch-entity-merge-case","level":"4","number":"10.5.11.6","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge-case","title":"5.5.11.5\tBatch Entity Merge case"},"subsections":[]}]},{"section":{"id":"tabmerge-patch-behaviour","level":"3","number":"10.5.12","path":"10-tabapi-operation-definition.html#tabmerge-patch-behaviour","title":"5.5.12\tMerge Patch Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-operations-to-local-scope","level":"3","number":"10.5.13","path":"10-tabapi-operation-definition.html#tablimiting-operations-to-local-scope","title":"5.5.13\tLimiting operations to local scope"},"subsections":[]},{"section":{"id":"tabdistributed-transactional-behaviour","level":"3","number":"10.5.14","path":"10-tabapi-operation-definition.html#tabdistributed-transactional-behaviour","title":"5.5.14\tDistributed Transactional Behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-information-provision","level":"2","number":"10.6","path":"10-tabapi-operation-definition.html#tabcontext-information-provision","title":"5.6\tContext Information Provision"},"subsections":[{"section":{"id":"tabcreate-entity","level":"3","number":"10.6.1","path":"10-tabapi-operation-definition.html#tabcreate-entity","title":"5.6.1\tCreate Entity"},"subsections":[{"section":{"id":"tabdescription","level":"4","number":"10.6.1.1","path":"10-tabapi-operation-definition.html#tabdescription","title":"5.6.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram","level":"4","number":"10.6.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram","title":"5.6.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data","level":"4","number":"10.6.1.3","path":"10-tabapi-operation-definition.html#tabinput-data","title":"5.6.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour","level":"4","number":"10.6.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour","title":"5.6.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data","level":"4","number":"10.6.1.5","path":"10-tabapi-operation-definition.html#taboutput-data","title":"5.6.1.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabupdate-attributes","level":"3","number":"10.6.2","path":"10-tabapi-operation-definition.html#tabupdate-attributes","title":"5.6.2\tUpdate Attributes"},"subsections":[{"section":{"id":"tabdescription-1","level":"4","number":"10.6.2.1","path":"10-tabapi-operation-definition.html#tabdescription-1","title":"5.6.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-1","level":"4","number":"10.6.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-1","title":"5.6.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-1","level":"4","number":"10.6.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-1","title":"5.6.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-1","level":"4","number":"10.6.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-1","title":"5.6.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-1","level":"4","number":"10.6.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-1","title":"5.6.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabappend-attributes","level":"3","number":"10.6.3","path":"10-tabapi-operation-definition.html#tabappend-attributes","title":"5.6.3\tAppend Attributes"},"subsections":[{"section":{"id":"tabdescription-2","level":"4","number":"10.6.3.1","path":"10-tabapi-operation-definition.html#tabdescription-2","title":"5.6.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-2","level":"4","number":"10.6.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-2","title":"5.6.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-2","level":"4","number":"10.6.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-2","title":"5.6.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-2","level":"4","number":"10.6.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-2","title":"5.6.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-2","level":"4","number":"10.6.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-2","title":"5.6.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabpartial-attribute-update","level":"3","number":"10.6.4","path":"10-tabapi-operation-definition.html#tabpartial-attribute-update","title":"5.6.4\tPartial Attribute update"},"subsections":[{"section":{"id":"tabdescription-3","level":"4","number":"10.6.4.1","path":"10-tabapi-operation-definition.html#tabdescription-3","title":"5.6.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-3","level":"4","number":"10.6.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-3","title":"5.6.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-3","level":"4","number":"10.6.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-3","title":"5.6.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-3","level":"4","number":"10.6.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-3","title":"5.6.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-3","level":"4","number":"10.6.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-3","title":"5.6.4.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute","level":"3","number":"10.6.5","path":"10-tabapi-operation-definition.html#tabdelete-attribute","title":"5.6.5\tDelete Attribute"},"subsections":[{"section":{"id":"tabdescription-4","level":"4","number":"10.6.5.1","path":"10-tabapi-operation-definition.html#tabdescription-4","title":"5.6.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-4","level":"4","number":"10.6.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-4","title":"5.6.5.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-4","level":"4","number":"10.6.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-4","title":"5.6.5.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-4","level":"4","number":"10.6.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-4","title":"5.6.5.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-4","level":"4","number":"10.6.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-4","title":"5.6.5.5\tOutput data"},"subsections":[]},{"section":{"id":"tabdescription-5","level":"4","number":"10.6.5.6","path":"10-tabapi-operation-definition.html#tabdescription-5","title":"5.6.6.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-5","level":"4","number":"10.6.5.7","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-5","title":"5.6.6.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-5","level":"4","number":"10.6.5.8","path":"10-tabapi-operation-definition.html#tabinput-data-5","title":"5.6.6.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-5","level":"4","number":"10.6.5.9","path":"10-tabapi-operation-definition.html#tabbehaviour-5","title":"5.6.6.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-5","level":"4","number":"10.6.5.10","path":"10-tabapi-operation-definition.html#taboutput-data-5","title":"5.6.6.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation","level":"3","number":"10.6.6","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation","title":"5.6.7\tBatch Entity Creation"},"subsections":[{"section":{"id":"tabdescription-6","level":"4","number":"10.6.6.1","path":"10-tabapi-operation-definition.html#tabdescription-6","title":"5.6.7.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-6","level":"4","number":"10.6.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-6","title":"5.6.7.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-6","level":"4","number":"10.6.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-6","title":"5.6.7.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-6","level":"4","number":"10.6.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-6","title":"5.6.7.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-6","level":"4","number":"10.6.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-6","title":"5.6.7.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-creation-or-update-upsert","level":"3","number":"10.6.7","path":"10-tabapi-operation-definition.html#tabbatch-entity-creation-or-update-upsert","title":"5.6.8\tBatch Entity Creation or Update (Upsert)"},"subsections":[{"section":{"id":"tabdescription-7","level":"4","number":"10.6.7.1","path":"10-tabapi-operation-definition.html#tabdescription-7","title":"5.6.8.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-7","level":"4","number":"10.6.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-7","title":"5.6.8.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-7","level":"4","number":"10.6.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-7","title":"5.6.8.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-7","level":"4","number":"10.6.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-7","title":"5.6.8.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-7","level":"4","number":"10.6.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-7","title":"5.6.8.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-update","level":"3","number":"10.6.8","path":"10-tabapi-operation-definition.html#tabbatch-entity-update","title":"5.6.9\tBatch Entity Update"},"subsections":[{"section":{"id":"tabdescription-8","level":"4","number":"10.6.8.1","path":"10-tabapi-operation-definition.html#tabdescription-8","title":"5.6.9.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-8","level":"4","number":"10.6.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-8","title":"5.6.9.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-8","level":"4","number":"10.6.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-8","title":"5.6.9.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-8","level":"4","number":"10.6.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-8","title":"5.6.9.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-8","level":"4","number":"10.6.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-8","title":"5.6.9.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-delete","level":"3","number":"10.6.9","path":"10-tabapi-operation-definition.html#tabbatch-entity-delete","title":"5.6.10\tBatch Entity Delete"},"subsections":[{"section":{"id":"tabdescription-9","level":"4","number":"10.6.9.1","path":"10-tabapi-operation-definition.html#tabdescription-9","title":"5.6.10.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-9","level":"4","number":"10.6.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-9","title":"5.6.10.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-9","level":"4","number":"10.6.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-9","title":"5.6.10.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-9","level":"4","number":"10.6.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-9","title":"5.6.10.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-9","level":"4","number":"10.6.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-9","title":"5.6.10.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabcreate-or-update-upsert-temporal-evolution-of-an-entity","level":"3","number":"10.6.10","path":"10-tabapi-operation-definition.html#tabcreate-or-update-upsert-temporal-evolution-of-an-entity","title":"5.6.11\tCreate or Update (Upsert) Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-10","level":"4","number":"10.6.10.1","path":"10-tabapi-operation-definition.html#tabdescription-10","title":"5.6.11.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-10","level":"4","number":"10.6.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-10","title":"5.6.11.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-10","level":"4","number":"10.6.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-10","title":"5.6.11.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-10","level":"4","number":"10.6.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-10","title":"5.6.11.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-10","level":"4","number":"10.6.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-10","title":"5.6.11.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabadd-attributes-to-temporal-evolution-of-an-entity","level":"3","number":"10.6.11","path":"10-tabapi-operation-definition.html#tabadd-attributes-to-temporal-evolution-of-an-entity","title":"5.6.12\tAdd Attributes to Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-11","level":"4","number":"10.6.11.1","path":"10-tabapi-operation-definition.html#tabdescription-11","title":"5.6.12.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-11","level":"4","number":"10.6.11.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-11","title":"5.6.12.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-11","level":"4","number":"10.6.11.3","path":"10-tabapi-operation-definition.html#tabinput-data-11","title":"5.6.12.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-11","level":"4","number":"10.6.11.4","path":"10-tabapi-operation-definition.html#tabbehaviour-11","title":"5.6.12.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-11","level":"4","number":"10.6.11.5","path":"10-tabapi-operation-definition.html#taboutput-data-11","title":"5.6.12.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.12","path":"10-tabapi-operation-definition.html#tabdelete-attribute-from-temporal-evolution-of-an-entity","title":"5.6.13\tDelete Attribute from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-12","level":"4","number":"10.6.12.1","path":"10-tabapi-operation-definition.html#tabdescription-12","title":"5.6.13.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-12","level":"4","number":"10.6.12.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-12","title":"5.6.13.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-12","level":"4","number":"10.6.12.3","path":"10-tabapi-operation-definition.html#tabinput-data-12","title":"5.6.13.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-12","level":"4","number":"10.6.12.4","path":"10-tabapi-operation-definition.html#tabbehaviour-12","title":"5.6.13.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-12","level":"4","number":"10.6.12.5","path":"10-tabapi-operation-definition.html#taboutput-data-12","title":"5.6.13.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","level":"3","number":"10.6.13","path":"10-tabapi-operation-definition.html#tabmodify-attribute-instance-in-temporal-evolution-of-an-entity","title":"5.6.14\tModify Attribute instance in Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-13","level":"4","number":"10.6.13.1","path":"10-tabapi-operation-definition.html#tabdescription-13","title":"5.6.14.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-13","level":"4","number":"10.6.13.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-13","title":"5.6.14.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-13","level":"4","number":"10.6.13.3","path":"10-tabapi-operation-definition.html#tabinput-data-13","title":"5.6.14.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-13","level":"4","number":"10.6.13.4","path":"10-tabapi-operation-definition.html#tabbehaviour-13","title":"5.6.14.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-13","level":"4","number":"10.6.13.5","path":"10-tabapi-operation-definition.html#taboutput-data-13","title":"5.6.14.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","level":"3","number":"10.6.14","path":"10-tabapi-operation-definition.html#tabdelete-attribute-instance-from-temporal-evolution-of-an-entity","title":"5.6.15\tDelete Attribute instance from Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-14","level":"4","number":"10.6.14.1","path":"10-tabapi-operation-definition.html#tabdescription-14","title":"5.6.15.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-14","level":"4","number":"10.6.14.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-14","title":"5.6.15.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-14","level":"4","number":"10.6.14.3","path":"10-tabapi-operation-definition.html#tabinput-data-14","title":"5.6.15.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-14","level":"4","number":"10.6.14.4","path":"10-tabapi-operation-definition.html#tabbehaviour-14","title":"5.6.15.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-14","level":"4","number":"10.6.14.5","path":"10-tabapi-operation-definition.html#taboutput-data-14","title":"5.6.15.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-temporal-evolution-of-an-entity","level":"3","number":"10.6.15","path":"10-tabapi-operation-definition.html#tabdelete-temporal-evolution-of-an-entity","title":"5.6.16\tDelete Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-15","level":"4","number":"10.6.15.1","path":"10-tabapi-operation-definition.html#tabdescription-15","title":"5.6.16.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-15","level":"4","number":"10.6.15.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-15","title":"5.6.16.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-15","level":"4","number":"10.6.15.3","path":"10-tabapi-operation-definition.html#tabinput-data-15","title":"5.6.16.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-15","level":"4","number":"10.6.15.4","path":"10-tabapi-operation-definition.html#tabbehaviour-15","title":"5.6.16.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-15","level":"4","number":"10.6.15.5","path":"10-tabapi-operation-definition.html#taboutput-data-15","title":"5.6.16.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabmerge-entity","level":"3","number":"10.6.16","path":"10-tabapi-operation-definition.html#tabmerge-entity","title":"5.6.17\tMerge Entity"},"subsections":[{"section":{"id":"tabdescription-16","level":"4","number":"10.6.16.1","path":"10-tabapi-operation-definition.html#tabdescription-16","title":"5.6.17.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-16","level":"4","number":"10.6.16.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-16","title":"5.6.17.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-16","level":"4","number":"10.6.16.3","path":"10-tabapi-operation-definition.html#tabinput-data-16","title":"5.6.17.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-16","level":"4","number":"10.6.16.4","path":"10-tabapi-operation-definition.html#tabbehaviour-16","title":"5.6.17.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-16","level":"4","number":"10.6.16.5","path":"10-tabapi-operation-definition.html#taboutput-data-16","title":"5.6.17.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabreplace-entity","level":"3","number":"10.6.17","path":"10-tabapi-operation-definition.html#tabreplace-entity","title":"5.6.18\tReplace Entity"},"subsections":[{"section":{"id":"tabdescription-17","level":"4","number":"10.6.17.1","path":"10-tabapi-operation-definition.html#tabdescription-17","title":"5.6.18.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-17","level":"4","number":"10.6.17.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-17","title":"5.6.18.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-17","level":"4","number":"10.6.17.3","path":"10-tabapi-operation-definition.html#tabinput-data-17","title":"5.6.18.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-17","level":"4","number":"10.6.17.4","path":"10-tabapi-operation-definition.html#tabbehaviour-17","title":"5.6.18.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-17","level":"4","number":"10.6.17.5","path":"10-tabapi-operation-definition.html#taboutput-data-17","title":"5.6.18.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabreplace-attribute","level":"3","number":"10.6.18","path":"10-tabapi-operation-definition.html#tabreplace-attribute","title":"5.6.19\tReplace Attribute"},"subsections":[{"section":{"id":"tabdescription-18","level":"4","number":"10.6.18.1","path":"10-tabapi-operation-definition.html#tabdescription-18","title":"5.6.19.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-18","level":"4","number":"10.6.18.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-18","title":"5.6.19.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-18","level":"4","number":"10.6.18.3","path":"10-tabapi-operation-definition.html#tabinput-data-18","title":"5.6.19.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-18","level":"4","number":"10.6.18.4","path":"10-tabapi-operation-definition.html#tabbehaviour-18","title":"5.6.19.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-18","level":"4","number":"10.6.18.5","path":"10-tabapi-operation-definition.html#taboutput-data-18","title":"5.6.19.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabbatch-entity-merge","level":"3","number":"10.6.19","path":"10-tabapi-operation-definition.html#tabbatch-entity-merge","title":"5.6.20\tBatch Entity Merge"},"subsections":[{"section":{"id":"tabdescription-19","level":"4","number":"10.6.19.1","path":"10-tabapi-operation-definition.html#tabdescription-19","title":"5.6.20.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-19","level":"4","number":"10.6.19.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-19","title":"5.6.20.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-19","level":"4","number":"10.6.19.3","path":"10-tabapi-operation-definition.html#tabinput-data-19","title":"5.6.20.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-19","level":"4","number":"10.6.19.4","path":"10-tabapi-operation-definition.html#tabbehaviour-19","title":"5.6.20.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-19","level":"4","number":"10.6.19.5","path":"10-tabapi-operation-definition.html#taboutput-data-19","title":"5.6.20.5\tOutput data"},"subsections":[]}]},{"section":{"id":"purge-entities","level":"3","number":"10.6.20","path":"10-tabapi-operation-definition.html#purge-entities","title":"5.6.21 Purge Entities"},"subsections":[{"section":{"id":"description","level":"4","number":"10.6.20.1","path":"10-tabapi-operation-definition.html#description","title":"5.6.21.1 Description"},"subsections":[]},{"section":{"id":"use-case-diagram","level":"4","number":"10.6.20.2","path":"10-tabapi-operation-definition.html#use-case-diagram","title":"5.6.21.2 Use case diagram"},"subsections":[]},{"section":{"id":"input-data","level":"4","number":"10.6.20.3","path":"10-tabapi-operation-definition.html#input-data","title":"5.6.21.3 Input data"},"subsections":[]},{"section":{"id":"behaviour","level":"4","number":"10.6.20.4","path":"10-tabapi-operation-definition.html#behaviour","title":"5.6.21.4 Behaviour"},"subsections":[]},{"section":{"id":"output-data","level":"4","number":"10.6.20.5","path":"10-tabapi-operation-definition.html#output-data","title":"5.6.21.5 Output data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-information-consumption","level":"2","number":"10.7","path":"10-tabapi-operation-definition.html#tabcontext-information-consumption","title":"5.7\tContext Information Consumption"},"subsections":[{"section":{"id":"tabretrieve-entity","level":"3","number":"10.7.1","path":"10-tabapi-operation-definition.html#tabretrieve-entity","title":"5.7.1\tRetrieve Entity"},"subsections":[{"section":{"id":"tabdescription-20","level":"4","number":"10.7.1.1","path":"10-tabapi-operation-definition.html#tabdescription-20","title":"5.7.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-20","level":"4","number":"10.7.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-20","title":"5.7.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-20","level":"4","number":"10.7.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-20","title":"5.7.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-20","level":"4","number":"10.7.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-20","title":"5.7.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-20","level":"4","number":"10.7.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-20","title":"5.7.1.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabquery-entities","level":"3","number":"10.7.2","path":"10-tabapi-operation-definition.html#tabquery-entities","title":"5.7.2\tQuery Entities"},"subsections":[{"section":{"id":"tabdescription-21","level":"4","number":"10.7.2.1","path":"10-tabapi-operation-definition.html#tabdescription-21","title":"5.7.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-21","level":"4","number":"10.7.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-21","title":"5.7.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-21","level":"4","number":"10.7.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-21","title":"5.7.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-21","level":"4","number":"10.7.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-21","title":"5.7.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-21","level":"4","number":"10.7.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-21","title":"5.7.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-temporal-evolution-of-an-entity","level":"3","number":"10.7.3","path":"10-tabapi-operation-definition.html#tabretrieve-temporal-evolution-of-an-entity","title":"5.7.3\tRetrieve Temporal Evolution of an Entity"},"subsections":[{"section":{"id":"tabdescription-22","level":"4","number":"10.7.3.1","path":"10-tabapi-operation-definition.html#tabdescription-22","title":"5.7.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-22","level":"4","number":"10.7.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-22","title":"5.7.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-22","level":"4","number":"10.7.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-22","title":"5.7.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-22","level":"4","number":"10.7.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-22","title":"5.7.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-22","level":"4","number":"10.7.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-22","title":"5.7.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabquery-temporal-evolution-of-entities","level":"3","number":"10.7.4","path":"10-tabapi-operation-definition.html#tabquery-temporal-evolution-of-entities","title":"5.7.4\tQuery Temporal Evolution of Entities"},"subsections":[{"section":{"id":"tabdescription-23","level":"4","number":"10.7.4.1","path":"10-tabapi-operation-definition.html#tabdescription-23","title":"5.7.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-23","level":"4","number":"10.7.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-23","title":"5.7.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-23","level":"4","number":"10.7.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-23","title":"5.7.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-23","level":"4","number":"10.7.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-23","title":"5.7.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-23","level":"4","number":"10.7.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-23","title":"5.7.4.5\tOutput Data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-types","level":"3","number":"10.7.5","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-types","title":"5.7.5\tRetrieve Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-24","level":"4","number":"10.7.5.1","path":"10-tabapi-operation-definition.html#tabdescription-24","title":"5.7.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-24","level":"4","number":"10.7.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-24","title":"5.7.5.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-24","level":"4","number":"10.7.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-24","title":"5.7.5.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-24","level":"4","number":"10.7.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-24","title":"5.7.5.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-24","level":"4","number":"10.7.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-24","title":"5.7.5.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-entity-types","level":"3","number":"10.7.6","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-entity-types","title":"5.7.6\tRetrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"tabdescription-25","level":"4","number":"10.7.6.1","path":"10-tabapi-operation-definition.html#tabdescription-25","title":"5.7.6.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-25","level":"4","number":"10.7.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-25","title":"5.7.6.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-25","level":"4","number":"10.7.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-25","title":"5.7.6.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-25","level":"4","number":"10.7.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-25","title":"5.7.6.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-25","level":"4","number":"10.7.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-25","title":"5.7.6.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-entity-type-information","level":"3","number":"10.7.7","path":"10-tabapi-operation-definition.html#tabretrieve-available-entity-type-information","title":"5.7.7\tRetrieve Available Entity Type Information"},"subsections":[{"section":{"id":"tabdescription-26","level":"4","number":"10.7.7.1","path":"10-tabapi-operation-definition.html#tabdescription-26","title":"5.7.7.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-26","level":"4","number":"10.7.7.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-26","title":"5.7.7.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-26","level":"4","number":"10.7.7.3","path":"10-tabapi-operation-definition.html#tabinput-data-26","title":"5.7.7.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-26","level":"4","number":"10.7.7.4","path":"10-tabapi-operation-definition.html#tabbehaviour-26","title":"5.7.7.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-26","level":"4","number":"10.7.7.5","path":"10-tabapi-operation-definition.html#taboutput-data-26","title":"5.7.7.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attributes","level":"3","number":"10.7.8","path":"10-tabapi-operation-definition.html#tabretrieve-available-attributes","title":"5.7.8\tRetrieve Available Attributes"},"subsections":[{"section":{"id":"tabdescription-27","level":"4","number":"10.7.8.1","path":"10-tabapi-operation-definition.html#tabdescription-27","title":"5.7.8.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-27","level":"4","number":"10.7.8.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-27","title":"5.7.8.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-27","level":"4","number":"10.7.8.3","path":"10-tabapi-operation-definition.html#tabinput-data-27","title":"5.7.8.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-27","level":"4","number":"10.7.8.4","path":"10-tabapi-operation-definition.html#tabbehaviour-27","title":"5.7.8.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-27","level":"4","number":"10.7.8.5","path":"10-tabapi-operation-definition.html#taboutput-data-27","title":"5.7.8.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-details-of-available-attributes","level":"3","number":"10.7.9","path":"10-tabapi-operation-definition.html#tabretrieve-details-of-available-attributes","title":"5.7.9\tRetrieve Details of Available Attributes"},"subsections":[{"section":{"id":"tabdescription-28","level":"4","number":"10.7.9.1","path":"10-tabapi-operation-definition.html#tabdescription-28","title":"5.7.9.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-28","level":"4","number":"10.7.9.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-28","title":"5.7.9.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-28","level":"4","number":"10.7.9.3","path":"10-tabapi-operation-definition.html#tabinput-data-28","title":"5.7.9.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-28","level":"4","number":"10.7.9.4","path":"10-tabapi-operation-definition.html#tabbehaviour-28","title":"5.7.9.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-28","level":"4","number":"10.7.9.5","path":"10-tabapi-operation-definition.html#taboutput-data-28","title":"5.7.9.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-available-attribute-information","level":"3","number":"10.7.10","path":"10-tabapi-operation-definition.html#tabretrieve-available-attribute-information","title":"5.7.10\tRetrieve Available Attribute Information"},"subsections":[{"section":{"id":"tabdescription-29","level":"4","number":"10.7.10.1","path":"10-tabapi-operation-definition.html#tabdescription-29","title":"5.7.10.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-29","level":"4","number":"10.7.10.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-29","title":"5.7.10.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-29","level":"4","number":"10.7.10.3","path":"10-tabapi-operation-definition.html#tabinput-data-29","title":"5.7.10.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-29","level":"4","number":"10.7.10.4","path":"10-tabapi-operation-definition.html#tabbehaviour-29","title":"5.7.10.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-29","level":"4","number":"10.7.10.5","path":"10-tabapi-operation-definition.html#taboutput-data-29","title":"5.7.10.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","level":"3","number":"10.7.11","path":"10-tabapi-operation-definition.html#tabarchitecture-related-aspects-of-retrieval-of-entity-types-and-attributes","title":"5.7.11\tArchitecture-related aspects of retrieval of Entity Types and Attributes"},"subsections":[]}]},{"section":{"id":"tabcontext-information-subscription","level":"2","number":"10.8","path":"10-tabapi-operation-definition.html#tabcontext-information-subscription","title":"5.8\tContext Information Subscription"},"subsections":[{"section":{"id":"tabcreate-subscription","level":"3","number":"10.8.1","path":"10-tabapi-operation-definition.html#tabcreate-subscription","title":"5.8.1\tCreate Subscription"},"subsections":[{"section":{"id":"tabdescription-30","level":"4","number":"10.8.1.1","path":"10-tabapi-operation-definition.html#tabdescription-30","title":"5.8.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-30","level":"4","number":"10.8.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-30","title":"5.8.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-30","level":"4","number":"10.8.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-30","title":"5.8.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-30","level":"4","number":"10.8.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-30","title":"5.8.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-30","level":"4","number":"10.8.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-30","title":"5.8.1.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabupdate-subscription","level":"3","number":"10.8.2","path":"10-tabapi-operation-definition.html#tabupdate-subscription","title":"5.8.2\tUpdate Subscription"},"subsections":[{"section":{"id":"tabdescription-31","level":"4","number":"10.8.2.1","path":"10-tabapi-operation-definition.html#tabdescription-31","title":"5.8.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-31","level":"4","number":"10.8.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-31","title":"5.8.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-31","level":"4","number":"10.8.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-31","title":"5.8.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-31","level":"4","number":"10.8.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-31","title":"5.8.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-31","level":"4","number":"10.8.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-31","title":"5.8.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-subscription","level":"3","number":"10.8.3","path":"10-tabapi-operation-definition.html#tabretrieve-subscription","title":"5.8.3\tRetrieve Subscription"},"subsections":[{"section":{"id":"tabdescription-32","level":"4","number":"10.8.3.1","path":"10-tabapi-operation-definition.html#tabdescription-32","title":"5.8.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-32","level":"4","number":"10.8.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-32","title":"5.8.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-32","level":"4","number":"10.8.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-32","title":"5.8.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-32","level":"4","number":"10.8.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-32","title":"5.8.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-32","level":"4","number":"10.8.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-32","title":"5.8.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabquery-subscriptions","level":"3","number":"10.8.4","path":"10-tabapi-operation-definition.html#tabquery-subscriptions","title":"5.8.4\tQuery Subscriptions"},"subsections":[{"section":{"id":"tabdescription-33","level":"4","number":"10.8.4.1","path":"10-tabapi-operation-definition.html#tabdescription-33","title":"5.8.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-33","level":"4","number":"10.8.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-33","title":"5.8.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-33","level":"4","number":"10.8.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-33","title":"5.8.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-33","level":"4","number":"10.8.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-33","title":"5.8.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-33","level":"4","number":"10.8.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-33","title":"5.8.4.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-subscription","level":"3","number":"10.8.5","path":"10-tabapi-operation-definition.html#tabdelete-subscription","title":"5.8.5\tDelete Subscription"},"subsections":[{"section":{"id":"tabdescription-34","level":"4","number":"10.8.5.1","path":"10-tabapi-operation-definition.html#tabdescription-34","title":"5.8.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-34","level":"4","number":"10.8.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-34","title":"5.8.5.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-34","level":"4","number":"10.8.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-34","title":"5.8.5.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-34","level":"4","number":"10.8.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-34","title":"5.8.5.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-34","level":"4","number":"10.8.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-34","title":"5.8.5.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour","level":"3","number":"10.8.6","path":"10-tabapi-operation-definition.html#tabnotification-behaviour","title":"5.8.6\tNotification behaviour"},"subsections":[]}]},{"section":{"id":"tabcontext-source-registration","level":"2","number":"10.9","path":"10-tabapi-operation-definition.html#tabcontext-source-registration","title":"5.9\tContext Source Registration"},"subsections":[{"section":{"id":"tabintroduction-17","level":"3","number":"10.9.1","path":"10-tabapi-operation-definition.html#tabintroduction-17","title":"5.9.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabregister-context-source","level":"3","number":"10.9.2","path":"10-tabapi-operation-definition.html#tabregister-context-source","title":"5.9.2\tRegister Context Source"},"subsections":[{"section":{"id":"tabdescription-35","level":"4","number":"10.9.2.1","path":"10-tabapi-operation-definition.html#tabdescription-35","title":"5.9.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-35","level":"4","number":"10.9.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-35","title":"5.9.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-35","level":"4","number":"10.9.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-35","title":"5.9.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-35","level":"4","number":"10.9.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-35","title":"5.9.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-35","level":"4","number":"10.9.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-35","title":"5.9.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration","level":"3","number":"10.9.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration","title":"5.9.3\tUpdate Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-36","level":"4","number":"10.9.3.1","path":"10-tabapi-operation-definition.html#tabdescription-36","title":"5.9.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-36","level":"4","number":"10.9.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-36","title":"5.9.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-36","level":"4","number":"10.9.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-36","title":"5.9.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-36","level":"4","number":"10.9.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-36","title":"5.9.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-36","level":"4","number":"10.9.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-36","title":"5.9.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration","level":"3","number":"10.9.4","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration","title":"5.9.4\tDelete Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-37","level":"4","number":"10.9.4.1","path":"10-tabapi-operation-definition.html#tabdescription-37","title":"5.9.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-37","level":"4","number":"10.9.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-37","title":"5.9.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-37","level":"4","number":"10.9.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-37","title":"5.9.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-37","level":"4","number":"10.9.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-37","title":"5.9.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-37","level":"4","number":"10.9.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-37","title":"5.9.4.5\tOutput data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-discovery","level":"2","number":"10.10","path":"10-tabapi-operation-definition.html#tabcontext-source-discovery","title":"5.10\tContext Source Discovery"},"subsections":[{"section":{"id":"tabretrieve-context-source-registration","level":"3","number":"10.10.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration","title":"5.10.1\tRetrieve Context Source Registration"},"subsections":[{"section":{"id":"tabdescription-38","level":"4","number":"10.10.1.1","path":"10-tabapi-operation-definition.html#tabdescription-38","title":"5.10.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-38","level":"4","number":"10.10.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-38","title":"5.10.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-38","level":"4","number":"10.10.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-38","title":"5.10.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-38","level":"4","number":"10.10.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-38","title":"5.10.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-38","level":"4","number":"10.10.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-38","title":"5.10.1.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registrations","level":"3","number":"10.10.2","path":"10-tabapi-operation-definition.html#tabquery-context-source-registrations","title":"5.10.2\tQuery Context Source Registrations"},"subsections":[{"section":{"id":"tabdescription-39","level":"4","number":"10.10.2.1","path":"10-tabapi-operation-definition.html#tabdescription-39","title":"5.10.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-39","level":"4","number":"10.10.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-39","title":"5.10.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-39","level":"4","number":"10.10.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-39","title":"5.10.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-39","level":"4","number":"10.10.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-39","title":"5.10.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-39","level":"4","number":"10.10.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-39","title":"5.10.2.5\tOutput data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-registration-subscription","level":"2","number":"10.11","path":"10-tabapi-operation-definition.html#tabcontext-source-registration-subscription","title":"5.11\tContext Source Registration Subscription"},"subsections":[{"section":{"id":"tabintroduction-18","level":"3","number":"10.11.1","path":"10-tabapi-operation-definition.html#tabintroduction-18","title":"5.11.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabcreate-context-source-registration-subscription","level":"3","number":"10.11.2","path":"10-tabapi-operation-definition.html#tabcreate-context-source-registration-subscription","title":"5.11.2\tCreate Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-40","level":"4","number":"10.11.2.1","path":"10-tabapi-operation-definition.html#tabdescription-40","title":"5.11.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-40","level":"4","number":"10.11.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-40","title":"5.11.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-40","level":"4","number":"10.11.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-40","title":"5.11.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-40","level":"4","number":"10.11.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-40","title":"5.11.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-40","level":"4","number":"10.11.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-40","title":"5.11.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabupdate-context-source-registration-subscription","level":"3","number":"10.11.3","path":"10-tabapi-operation-definition.html#tabupdate-context-source-registration-subscription","title":"5.11.3\tUpdate Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-41","level":"4","number":"10.11.3.1","path":"10-tabapi-operation-definition.html#tabdescription-41","title":"5.11.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-41","level":"4","number":"10.11.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-41","title":"5.11.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-41","level":"4","number":"10.11.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-41","title":"5.11.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-41","level":"4","number":"10.11.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-41","title":"5.11.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-41","level":"4","number":"10.11.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-41","title":"5.11.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabretrieve-context-source-registration-subscription","level":"3","number":"10.11.4","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-registration-subscription","title":"5.11.4\tRetrieve Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-42","level":"4","number":"10.11.4.1","path":"10-tabapi-operation-definition.html#tabdescription-42","title":"5.11.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-42","level":"4","number":"10.11.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-42","title":"5.11.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-42","level":"4","number":"10.11.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-42","title":"5.11.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-42","level":"4","number":"10.11.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-42","title":"5.11.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-42","level":"4","number":"10.11.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-42","title":"5.11.4.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabquery-context-source-registration-subscriptions","level":"3","number":"10.11.5","path":"10-tabapi-operation-definition.html#tabquery-context-source-registration-subscriptions","title":"5.11.5\tQuery Context Source Registration Subscriptions"},"subsections":[{"section":{"id":"tabdescription-43","level":"4","number":"10.11.5.1","path":"10-tabapi-operation-definition.html#tabdescription-43","title":"5.11.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-43","level":"4","number":"10.11.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-43","title":"5.11.5.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-43","level":"4","number":"10.11.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-43","title":"5.11.5.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-43","level":"4","number":"10.11.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-43","title":"5.11.5.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-43","level":"4","number":"10.11.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-43","title":"5.11.5.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-context-source-registration-subscription","level":"3","number":"10.11.6","path":"10-tabapi-operation-definition.html#tabdelete-context-source-registration-subscription","title":"5.11.6\tDelete Context Source Registration Subscription"},"subsections":[{"section":{"id":"tabdescription-44","level":"4","number":"10.11.6.1","path":"10-tabapi-operation-definition.html#tabdescription-44","title":"5.11.6.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-44","level":"4","number":"10.11.6.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-44","title":"5.11.6.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-44","level":"4","number":"10.11.6.3","path":"10-tabapi-operation-definition.html#tabinput-data-44","title":"5.11.6.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-44","level":"4","number":"10.11.6.4","path":"10-tabapi-operation-definition.html#tabbehaviour-44","title":"5.11.6.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-44","level":"4","number":"10.11.6.5","path":"10-tabapi-operation-definition.html#taboutput-data-44","title":"5.11.6.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabnotification-behaviour-1","level":"3","number":"10.11.7","path":"10-tabapi-operation-definition.html#tabnotification-behaviour-1","title":"5.11.7\tNotification behaviour"},"subsections":[]}]},{"section":{"id":"ondemand_char_color_000000-5.12tab-ondemand_char_color_000000-matching-context-source-registrations","level":"2","number":"10.12","path":"10-tabapi-operation-definition.html#ondemand_char_color_000000-5.12tab-ondemand_char_color_000000-matching-context-source-registrations","title":"5.12\tMatching Context Source Registrations"},"subsections":[]},{"section":{"id":"tabstoring-managing-and-serving-contexts","level":"2","number":"10.13","path":"10-tabapi-operation-definition.html#tabstoring-managing-and-serving-contexts","title":"5.13\tStoring, Managing and Serving @contexts"},"subsections":[{"section":{"id":"tabintroduction-19","level":"3","number":"10.13.1","path":"10-tabapi-operation-definition.html#tabintroduction-19","title":"5.13.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabadd-context","level":"3","number":"10.13.2","path":"10-tabapi-operation-definition.html#tabadd-context","title":"5.13.2\tAdd @context"},"subsections":[{"section":{"id":"tabdescription-45","level":"4","number":"10.13.2.1","path":"10-tabapi-operation-definition.html#tabdescription-45","title":"5.13.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-45","level":"4","number":"10.13.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-45","title":"5.13.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-45","level":"4","number":"10.13.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-45","title":"5.13.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-45","level":"4","number":"10.13.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-45","title":"5.13.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-45","level":"4","number":"10.13.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-45","title":"5.13.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tablist-contexts","level":"3","number":"10.13.3","path":"10-tabapi-operation-definition.html#tablist-contexts","title":"5.13.3\tList @contexts"},"subsections":[{"section":{"id":"tabdescription-46","level":"4","number":"10.13.3.1","path":"10-tabapi-operation-definition.html#tabdescription-46","title":"5.13.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-46","level":"4","number":"10.13.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-46","title":"5.13.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-46","level":"4","number":"10.13.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-46","title":"5.13.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-46","level":"4","number":"10.13.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-46","title":"5.13.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-46","level":"4","number":"10.13.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-46","title":"5.13.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabserve-context","level":"3","number":"10.13.4","path":"10-tabapi-operation-definition.html#tabserve-context","title":"5.13.4\tServe @context"},"subsections":[{"section":{"id":"tabdescription-47","level":"4","number":"10.13.4.1","path":"10-tabapi-operation-definition.html#tabdescription-47","title":"5.13.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-47","level":"4","number":"10.13.4.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-47","title":"5.13.4.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-47","level":"4","number":"10.13.4.3","path":"10-tabapi-operation-definition.html#tabinput-data-47","title":"5.13.4.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-47","level":"4","number":"10.13.4.4","path":"10-tabapi-operation-definition.html#tabbehaviour-47","title":"5.13.4.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-47","level":"4","number":"10.13.4.5","path":"10-tabapi-operation-definition.html#taboutput-data-47","title":"5.13.4.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-and-reload-context","level":"3","number":"10.13.5","path":"10-tabapi-operation-definition.html#tabdelete-and-reload-context","title":"5.13.5\tDelete and Reload @context"},"subsections":[{"section":{"id":"tabdescription-48","level":"4","number":"10.13.5.1","path":"10-tabapi-operation-definition.html#tabdescription-48","title":"5.13.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-48","level":"4","number":"10.13.5.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-48","title":"5.13.5.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-48","level":"4","number":"10.13.5.3","path":"10-tabapi-operation-definition.html#tabinput-data-48","title":"5.13.5.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-48","level":"4","number":"10.13.5.4","path":"10-tabapi-operation-definition.html#tabbehaviour-48","title":"5.13.5.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-48","level":"4","number":"10.13.5.5","path":"10-tabapi-operation-definition.html#taboutput-data-48","title":"5.13.5.5\tOutput data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-entity-mapping","level":"2","number":"10.14","path":"10-tabapi-operation-definition.html#tabcontext-source-entity-mapping","title":"5.14\tContext Source Entity Mapping"},"subsections":[{"section":{"id":"tabretrieve-entitymap","level":"3","number":"10.14.1","path":"10-tabapi-operation-definition.html#tabretrieve-entitymap","title":"5.14.1\tRetrieve EntityMap"},"subsections":[{"section":{"id":"tabdescription-49","level":"4","number":"10.14.1.1","path":"10-tabapi-operation-definition.html#tabdescription-49","title":"5.14.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-49","level":"4","number":"10.14.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-49","title":"5.14.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-49","level":"4","number":"10.14.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-49","title":"5.14.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-49","level":"4","number":"10.14.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-49","title":"5.14.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-49","level":"4","number":"10.14.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-49","title":"5.14.1.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabupdate-entitymap","level":"3","number":"10.14.2","path":"10-tabapi-operation-definition.html#tabupdate-entitymap","title":"5.14.2\tUpdate EntityMap"},"subsections":[{"section":{"id":"tabdescription-50","level":"4","number":"10.14.2.1","path":"10-tabapi-operation-definition.html#tabdescription-50","title":"5.14.2.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-50","level":"4","number":"10.14.2.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-50","title":"5.14.2.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-50","level":"4","number":"10.14.2.3","path":"10-tabapi-operation-definition.html#tabinput-data-50","title":"5.14.2.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-50","level":"4","number":"10.14.2.4","path":"10-tabapi-operation-definition.html#tabbehaviour-50","title":"5.14.2.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-50","level":"4","number":"10.14.2.5","path":"10-tabapi-operation-definition.html#taboutput-data-50","title":"5.14.2.5\tOutput data"},"subsections":[]}]},{"section":{"id":"tabdelete-entitymap","level":"3","number":"10.14.3","path":"10-tabapi-operation-definition.html#tabdelete-entitymap","title":"5.14.3\tDelete EntityMap"},"subsections":[{"section":{"id":"tabdescription-51","level":"4","number":"10.14.3.1","path":"10-tabapi-operation-definition.html#tabdescription-51","title":"5.14.3.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-51","level":"4","number":"10.14.3.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-51","title":"5.14.3.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-51","level":"4","number":"10.14.3.3","path":"10-tabapi-operation-definition.html#tabinput-data-51","title":"5.14.3.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-51","level":"4","number":"10.14.3.4","path":"10-tabapi-operation-definition.html#tabbehaviour-51","title":"5.14.3.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-51","level":"4","number":"10.14.3.5","path":"10-tabapi-operation-definition.html#taboutput-data-51","title":"5.14.3.5\tOutput data"},"subsections":[]}]},{"section":{"id":"create-entitymap-for-query-entities","level":"3","number":"10.14.4","path":"10-tabapi-operation-definition.html#create-entitymap-for-query-entities","title":"5.14.4 Create EntityMap for Query Entities"},"subsections":[{"section":{"id":"description-1","level":"4","number":"10.14.4.1","path":"10-tabapi-operation-definition.html#description-1","title":"5.14.4.1 Description"},"subsections":[]},{"section":{"id":"use-case-diagram-1","level":"4","number":"10.14.4.2","path":"10-tabapi-operation-definition.html#use-case-diagram-1","title":"5.14.4.2 Use case diagram"},"subsections":[]},{"section":{"id":"input-data-1","level":"4","number":"10.14.4.3","path":"10-tabapi-operation-definition.html#input-data-1","title":"5.14.4.3 Input data"},"subsections":[]},{"section":{"id":"behaviour-1","level":"4","number":"10.14.4.4","path":"10-tabapi-operation-definition.html#behaviour-1","title":"5.14.4.4 Behaviour"},"subsections":[]},{"section":{"id":"output-data-1","level":"4","number":"10.14.4.5","path":"10-tabapi-operation-definition.html#output-data-1","title":"5.14.4.5 Output data"},"subsections":[]}]},{"section":{"id":"create-entitymap-for-query-temporal-evolution-of-entities","level":"3","number":"10.14.5","path":"10-tabapi-operation-definition.html#create-entitymap-for-query-temporal-evolution-of-entities","title":"5.14.5 Create EntityMap for Query Temporal Evolution of Entities"},"subsections":[{"section":{"id":"description-2","level":"4","number":"10.14.5.1","path":"10-tabapi-operation-definition.html#description-2","title":"5.14.5.1 Description"},"subsections":[]},{"section":{"id":"use-case-diagram-2","level":"4","number":"10.14.5.2","path":"10-tabapi-operation-definition.html#use-case-diagram-2","title":"5.14.5.2 Use case diagram"},"subsections":[]},{"section":{"id":"input-data-2","level":"4","number":"10.14.5.3","path":"10-tabapi-operation-definition.html#input-data-2","title":"5.14.5.3 Input data"},"subsections":[]},{"section":{"id":"behaviour-2","level":"4","number":"10.14.5.4","path":"10-tabapi-operation-definition.html#behaviour-2","title":"5.14.5.4 Behaviour"},"subsections":[]},{"section":{"id":"output-data-2","level":"4","number":"10.14.5.5","path":"10-tabapi-operation-definition.html#output-data-2","title":"5.7.4.5 Output Data"},"subsections":[]}]}]},{"section":{"id":"tabcontext-source-identity-information","level":"2","number":"10.15","path":"10-tabapi-operation-definition.html#tabcontext-source-identity-information","title":"5.15\tContext Source Identity Information"},"subsections":[{"section":{"id":"tabretrieve-context-source-identity-information","level":"3","number":"10.15.1","path":"10-tabapi-operation-definition.html#tabretrieve-context-source-identity-information","title":"5.15.1\tRetrieve Context Source Identity Information"},"subsections":[{"section":{"id":"tabdescription-52","level":"4","number":"10.15.1.1","path":"10-tabapi-operation-definition.html#tabdescription-52","title":"5.15.1.1\tDescription"},"subsections":[]},{"section":{"id":"tabuse-case-diagram-52","level":"4","number":"10.15.1.2","path":"10-tabapi-operation-definition.html#tabuse-case-diagram-52","title":"5.15.1.2\tUse case diagram"},"subsections":[]},{"section":{"id":"tabinput-data-52","level":"4","number":"10.15.1.3","path":"10-tabapi-operation-definition.html#tabinput-data-52","title":"5.15.1.3\tInput data"},"subsections":[]},{"section":{"id":"tabbehaviour-52","level":"4","number":"10.15.1.4","path":"10-tabapi-operation-definition.html#tabbehaviour-52","title":"5.15.1.4\tBehaviour"},"subsections":[]},{"section":{"id":"taboutput-data-52","level":"4","number":"10.15.1.5","path":"10-tabapi-operation-definition.html#taboutput-data-52","title":"5.14.1.5\tOutput data"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-http-binding","level":"1","number":"11","path":"11-tabapi-http-binding.html#tabapi-http-binding","title":"6\tAPI HTTP Binding"},"subsections":[{"section":{"id":"tabintroduction-20","level":"2","number":"11.1","path":"11-tabapi-http-binding.html#tabintroduction-20","title":"6.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabglobal-definitions-and-resource-structure","level":"2","number":"11.2","path":"11-tabapi-http-binding.html#tabglobal-definitions-and-resource-structure","title":"6.2\tGlobal Definitions and Resource Structure"},"subsections":[]},{"section":{"id":"tabcommon-behaviours-1","level":"2","number":"11.3","path":"11-tabapi-http-binding.html#tabcommon-behaviours-1","title":"6.3\tCommon Behaviours"},"subsections":[{"section":{"id":"tabintroduction-21","level":"3","number":"11.3.1","path":"11-tabapi-http-binding.html#tabintroduction-21","title":"6.3.1\tIntroduction"},"subsections":[]},{"section":{"id":"taberror-types-1","level":"3","number":"11.3.2","path":"11-tabapi-http-binding.html#taberror-types-1","title":"6.3.2\tError Types"},"subsections":[]},{"section":{"id":"tabreporting-errors","level":"3","number":"11.3.3","path":"11-tabapi-http-binding.html#tabreporting-errors","title":"6.3.3\tReporting errors"},"subsections":[]},{"section":{"id":"tabhttp-request-preconditions","level":"3","number":"11.3.4","path":"11-tabapi-http-binding.html#tabhttp-request-preconditions","title":"6.3.4\tHTTP request preconditions"},"subsections":[]},{"section":{"id":"tabjson-ld-context-resolution","level":"3","number":"11.3.5","path":"11-tabapi-http-binding.html#tabjson-ld-context-resolution","title":"6.3.5\tJSON-LD @context resolution"},"subsections":[]},{"section":{"id":"tabhttp-response-common-requirements","level":"3","number":"11.3.6","path":"11-tabapi-http-binding.html#tabhttp-response-common-requirements","title":"6.3.6\tHTTP response common requirements"},"subsections":[]},{"section":{"id":"tabrepresentation-of-entities","level":"3","number":"11.3.7","path":"11-tabapi-http-binding.html#tabrepresentation-of-entities","title":"6.3.7\tRepresentation of Entities"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-2","level":"3","number":"11.3.8","path":"11-tabapi-http-binding.html#tabnotification-behaviour-2","title":"6.3.8\tNotification behaviour"},"subsections":[]},{"section":{"id":"tabcsource-notification-behaviour","level":"3","number":"11.3.9","path":"11-tabapi-http-binding.html#tabcsource-notification-behaviour","title":"6.3.9\tCsource Notification behaviour"},"subsections":[]},{"section":{"id":"tabpagination-behaviour-1","level":"3","number":"11.3.10","path":"11-tabapi-http-binding.html#tabpagination-behaviour-1","title":"6.3.10\tPagination behaviour"},"subsections":[]},{"section":{"id":"tabincluding-system-attributes","level":"3","number":"11.3.11","path":"11-tabapi-http-binding.html#tabincluding-system-attributes","title":"6.3.11\tIncluding system Attributes"},"subsections":[]},{"section":{"id":"tabsimplified-or-aggregated-temporal-representation-of-entities","level":"3","number":"11.3.12","path":"11-tabapi-http-binding.html#tabsimplified-or-aggregated-temporal-representation-of-entities","title":"6.3.12\tSimplified or aggregated temporal representation of Entities"},"subsections":[]},{"section":{"id":"tabcounting-number-of-results","level":"3","number":"11.3.13","path":"11-tabapi-http-binding.html#tabcounting-number-of-results","title":"6.3.13\tCounting number of results"},"subsections":[]},{"section":{"id":"tabtenant-specification","level":"3","number":"11.3.14","path":"11-tabapi-http-binding.html#tabtenant-specification","title":"6.3.14\tTenant specification"},"subsections":[]},{"section":{"id":"tabgeojson-representation-of-spatially-bound-entities","level":"3","number":"11.3.15","path":"11-tabapi-http-binding.html#tabgeojson-representation-of-spatially-bound-entities","title":"6.3.15\tGeoJSON representation of spatially bound entities"},"subsections":[]},{"section":{"id":"tabexpiration-time-for-cached-contexts","level":"3","number":"11.3.16","path":"11-tabapi-http-binding.html#tabexpiration-time-for-cached-contexts","title":"6.3.16\tExpiration time for cached @contexts"},"subsections":[]},{"section":{"id":"tabdistributed-operations-caching-and-timeout-behaviour","level":"3","number":"11.3.17","path":"11-tabapi-http-binding.html#tabdistributed-operations-caching-and-timeout-behaviour","title":"6.3.17\tDistributed Operations Caching and Timeout Behaviour"},"subsections":[]},{"section":{"id":"tablimiting-distributed-operations","level":"3","number":"11.3.18","path":"11-tabapi-http-binding.html#tablimiting-distributed-operations","title":"6.3.18\tLimiting Distributed Operations"},"subsections":[]},{"section":{"id":"tabextra-information-to-provide-when-contacting-context-source-1","level":"3","number":"11.3.19","path":"11-tabapi-http-binding.html#tabextra-information-to-provide-when-contacting-context-source-1","title":"6.3.19\tExtra information to provide when contacting Context Source"},"subsections":[]},{"section":{"id":"tabinvalid-parameters","level":"3","number":"11.3.20","path":"11-tabapi-http-binding.html#tabinvalid-parameters","title":"6.3.20\tInvalid parameters"},"subsections":[]},{"section":{"id":"optional-profile-information-regarding-versioning-and-datatype-conformance","level":"3","number":"11.3.21","path":"11-tabapi-http-binding.html#optional-profile-information-regarding-versioning-and-datatype-conformance","title":"6.3.21 Optional profile information regarding versioning and datatype conformance"},"subsections":[]}]},{"section":{"id":"tabresource-entities","level":"2","number":"11.4","path":"11-tabapi-http-binding.html#tabresource-entities","title":"6.4\tResource: entities/"},"subsections":[{"section":{"id":"tabdescription-53","level":"3","number":"11.4.1","path":"11-tabapi-http-binding.html#tabdescription-53","title":"6.4.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition","level":"3","number":"11.4.2","path":"11-tabapi-http-binding.html#tabresource-definition","title":"6.4.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods","level":"3","number":"11.4.3","path":"11-tabapi-http-binding.html#tabresource-methods","title":"6.4.3\tResource methods"},"subsections":[{"section":{"id":"tabpost","level":"4","number":"11.4.3.1","path":"11-tabapi-http-binding.html#tabpost","title":"6.4.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget","level":"4","number":"11.4.3.2","path":"11-tabapi-http-binding.html#tabget","title":"6.4.3.2\tGET"},"subsections":[]},{"section":{"id":"delete","level":"4","number":"11.4.3.3","path":"11-tabapi-http-binding.html#delete","title":"6.4.3.3 DELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityid","level":"2","number":"11.5","path":"11-tabapi-http-binding.html#tabresource-entitiesentityid","title":"6.5\tResource: entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-54","level":"3","number":"11.5.1","path":"11-tabapi-http-binding.html#tabdescription-54","title":"6.5.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-1","level":"3","number":"11.5.2","path":"11-tabapi-http-binding.html#tabresource-definition-1","title":"6.5.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-1","level":"3","number":"11.5.3","path":"11-tabapi-http-binding.html#tabresource-methods-1","title":"6.5.3\tResource methods"},"subsections":[{"section":{"id":"tabget-1","level":"4","number":"11.5.3.1","path":"11-tabapi-http-binding.html#tabget-1","title":"6.5.3.1\tGET"},"subsections":[]},{"section":{"id":"tabdelete","level":"4","number":"11.5.3.2","path":"11-tabapi-http-binding.html#tabdelete","title":"6.5.3.2\tDELETE"},"subsections":[]},{"section":{"id":"tabput","level":"4","number":"11.5.3.3","path":"11-tabapi-http-binding.html#tabput","title":"6.5.3.3\tPUT"},"subsections":[]},{"section":{"id":"tabpatch","level":"4","number":"11.5.3.4","path":"11-tabapi-http-binding.html#tabpatch","title":"6.5.3.4\tPATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrs","level":"2","number":"11.6","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrs","title":"6.6\tResource: entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-55","level":"3","number":"11.6.1","path":"11-tabapi-http-binding.html#tabdescription-55","title":"6.6.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-2","level":"3","number":"11.6.2","path":"11-tabapi-http-binding.html#tabresource-definition-2","title":"6.6.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-2","level":"3","number":"11.6.3","path":"11-tabapi-http-binding.html#tabresource-methods-2","title":"6.6.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-1","level":"4","number":"11.6.3.1","path":"11-tabapi-http-binding.html#tabpost-1","title":"6.6.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabpatch-1","level":"4","number":"11.6.3.2","path":"11-tabapi-http-binding.html#tabpatch-1","title":"6.6.3.2\tPATCH"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitiesentityidattrsattrid","level":"2","number":"11.7","path":"11-tabapi-http-binding.html#tabresource-entitiesentityidattrsattrid","title":"6.7\tResource: entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-56","level":"3","number":"11.7.1","path":"11-tabapi-http-binding.html#tabdescription-56","title":"6.7.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-3","level":"3","number":"11.7.2","path":"11-tabapi-http-binding.html#tabresource-definition-3","title":"6.7.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-3","level":"3","number":"11.7.3","path":"11-tabapi-http-binding.html#tabresource-methods-3","title":"6.7.3\tResource methods"},"subsections":[{"section":{"id":"tabpatch-2","level":"4","number":"11.7.3.1","path":"11-tabapi-http-binding.html#tabpatch-2","title":"6.7.3.1\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-1","level":"4","number":"11.7.3.2","path":"11-tabapi-http-binding.html#tabdelete-1","title":"6.7.3.2\tDELETE"},"subsections":[]},{"section":{"id":"tabput-1","level":"4","number":"11.7.3.3","path":"11-tabapi-http-binding.html#tabput-1","title":"6.7.3.3\tPUT"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrations","level":"2","number":"11.8","path":"11-tabapi-http-binding.html#tabresource-csourceregistrations","title":"6.8\tResource: csourceRegistrations/"},"subsections":[{"section":{"id":"tabdescription-57","level":"3","number":"11.8.1","path":"11-tabapi-http-binding.html#tabdescription-57","title":"6.8.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-4","level":"3","number":"11.8.2","path":"11-tabapi-http-binding.html#tabresource-definition-4","title":"6.8.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-4","level":"3","number":"11.8.3","path":"11-tabapi-http-binding.html#tabresource-methods-4","title":"6.8.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-2","level":"4","number":"11.8.3.1","path":"11-tabapi-http-binding.html#tabpost-2","title":"6.8.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget-2","level":"4","number":"11.8.3.2","path":"11-tabapi-http-binding.html#tabget-2","title":"6.8.3.2\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourceregistrationsregistrationid","level":"2","number":"11.9","path":"11-tabapi-http-binding.html#tabresource-csourceregistrationsregistrationid","title":"6.9\tResource: csourceRegistrations/{registrationId}"},"subsections":[{"section":{"id":"tabdescription-58","level":"3","number":"11.9.1","path":"11-tabapi-http-binding.html#tabdescription-58","title":"6.9.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-5","level":"3","number":"11.9.2","path":"11-tabapi-http-binding.html#tabresource-definition-5","title":"6.9.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-5","level":"3","number":"11.9.3","path":"11-tabapi-http-binding.html#tabresource-methods-5","title":"6.9.3\tResource methods"},"subsections":[{"section":{"id":"tabget-3","level":"4","number":"11.9.3.1","path":"11-tabapi-http-binding.html#tabget-3","title":"6.9.3.1\tGET"},"subsections":[]},{"section":{"id":"tabpatch-3","level":"4","number":"11.9.3.2","path":"11-tabapi-http-binding.html#tabpatch-3","title":"6.9.3.2\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-2","level":"4","number":"11.9.3.3","path":"11-tabapi-http-binding.html#tabdelete-2","title":"6.9.3.3\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptions","level":"2","number":"11.10","path":"11-tabapi-http-binding.html#tabresource-subscriptions","title":"6.10\tResource: subscriptions/"},"subsections":[{"section":{"id":"tabdescription-59","level":"3","number":"11.10.1","path":"11-tabapi-http-binding.html#tabdescription-59","title":"6.10.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-6","level":"3","number":"11.10.2","path":"11-tabapi-http-binding.html#tabresource-definition-6","title":"6.10.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-6","level":"3","number":"11.10.3","path":"11-tabapi-http-binding.html#tabresource-methods-6","title":"6.10.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-3","level":"4","number":"11.10.3.1","path":"11-tabapi-http-binding.html#tabpost-3","title":"6.10.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget-4","level":"4","number":"11.10.3.2","path":"11-tabapi-http-binding.html#tabget-4","title":"6.10.3.2\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-subscriptionssubscriptionid","level":"2","number":"11.11","path":"11-tabapi-http-binding.html#tabresource-subscriptionssubscriptionid","title":"6.11\tResource: subscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-60","level":"3","number":"11.11.1","path":"11-tabapi-http-binding.html#tabdescription-60","title":"6.11.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-7","level":"3","number":"11.11.2","path":"11-tabapi-http-binding.html#tabresource-definition-7","title":"6.11.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-7","level":"3","number":"11.11.3","path":"11-tabapi-http-binding.html#tabresource-methods-7","title":"6.11.3\tResource methods"},"subsections":[{"section":{"id":"tabget-5","level":"4","number":"11.11.3.1","path":"11-tabapi-http-binding.html#tabget-5","title":"6.11.3.1\tGET"},"subsections":[]},{"section":{"id":"tabpatch-4","level":"4","number":"11.11.3.2","path":"11-tabapi-http-binding.html#tabpatch-4","title":"6.11.3.2\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-3","level":"4","number":"11.11.3.3","path":"11-tabapi-http-binding.html#tabdelete-3","title":"6.11.3.3\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptions","level":"2","number":"11.12","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptions","title":"6.12\tResource: csourceSubscriptions/"},"subsections":[{"section":{"id":"tabdescription-61","level":"3","number":"11.12.1","path":"11-tabapi-http-binding.html#tabdescription-61","title":"6.12.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-8","level":"3","number":"11.12.2","path":"11-tabapi-http-binding.html#tabresource-definition-8","title":"6.12.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-8","level":"3","number":"11.12.3","path":"11-tabapi-http-binding.html#tabresource-methods-8","title":"6.12.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-4","level":"4","number":"11.12.3.1","path":"11-tabapi-http-binding.html#tabpost-4","title":"6.12.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget-6","level":"4","number":"11.12.3.2","path":"11-tabapi-http-binding.html#tabget-6","title":"6.12.3.2\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-csourcesubscriptionssubscriptionid","level":"2","number":"11.13","path":"11-tabapi-http-binding.html#tabresource-csourcesubscriptionssubscriptionid","title":"6.13\tResource: csourceSubscriptions/{subscriptionId}"},"subsections":[{"section":{"id":"tabdescription-62","level":"3","number":"11.13.1","path":"11-tabapi-http-binding.html#tabdescription-62","title":"6.13.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-9","level":"3","number":"11.13.2","path":"11-tabapi-http-binding.html#tabresource-definition-9","title":"6.13.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-9","level":"3","number":"11.13.3","path":"11-tabapi-http-binding.html#tabresource-methods-9","title":"6.13.3\tResource methods"},"subsections":[{"section":{"id":"tabget-7","level":"4","number":"11.13.3.1","path":"11-tabapi-http-binding.html#tabget-7","title":"6.13.3.1\tGET"},"subsections":[]},{"section":{"id":"tabpatch-5","level":"4","number":"11.13.3.2","path":"11-tabapi-http-binding.html#tabpatch-5","title":"6.13.3.2\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-4","level":"4","number":"11.13.3.3","path":"11-tabapi-http-binding.html#tabdelete-4","title":"6.13.3.3\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationscreate","level":"2","number":"11.14","path":"11-tabapi-http-binding.html#tabresource-entityoperationscreate","title":"6.14\tResource: entityOperations/create"},"subsections":[{"section":{"id":"tabdescription-63","level":"3","number":"11.14.1","path":"11-tabapi-http-binding.html#tabdescription-63","title":"6.14.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-10","level":"3","number":"11.14.2","path":"11-tabapi-http-binding.html#tabresource-definition-10","title":"6.14.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-10","level":"3","number":"11.14.3","path":"11-tabapi-http-binding.html#tabresource-methods-10","title":"6.14.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-5","level":"4","number":"11.14.3.1","path":"11-tabapi-http-binding.html#tabpost-5","title":"6.14.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupsert","level":"2","number":"11.15","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupsert","title":"6.15\tResource: entityOperations/upsert"},"subsections":[{"section":{"id":"tabdescription-64","level":"3","number":"11.15.1","path":"11-tabapi-http-binding.html#tabdescription-64","title":"6.15.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-11","level":"3","number":"11.15.2","path":"11-tabapi-http-binding.html#tabresource-definition-11","title":"6.15.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-11","level":"3","number":"11.15.3","path":"11-tabapi-http-binding.html#tabresource-methods-11","title":"6.15.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-6","level":"4","number":"11.15.3.1","path":"11-tabapi-http-binding.html#tabpost-6","title":"6.15.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsupdate","level":"2","number":"11.16","path":"11-tabapi-http-binding.html#tabresource-entityoperationsupdate","title":"6.16\tResource: entityOperations/update"},"subsections":[{"section":{"id":"tabdescription-65","level":"3","number":"11.16.1","path":"11-tabapi-http-binding.html#tabdescription-65","title":"6.16.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-12","level":"3","number":"11.16.2","path":"11-tabapi-http-binding.html#tabresource-definition-12","title":"6.16.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-12","level":"3","number":"11.16.3","path":"11-tabapi-http-binding.html#tabresource-methods-12","title":"6.16.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-7","level":"4","number":"11.16.3.1","path":"11-tabapi-http-binding.html#tabpost-7","title":"6.16.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsdelete","level":"2","number":"11.17","path":"11-tabapi-http-binding.html#tabresource-entityoperationsdelete","title":"6.17\tResource: entityOperations/delete"},"subsections":[{"section":{"id":"tabdescription-66","level":"3","number":"11.17.1","path":"11-tabapi-http-binding.html#tabdescription-66","title":"6.17.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-13","level":"3","number":"11.17.2","path":"11-tabapi-http-binding.html#tabresource-definition-13","title":"6.17.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-13","level":"3","number":"11.17.3","path":"11-tabapi-http-binding.html#tabresource-methods-13","title":"6.17.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-8","level":"4","number":"11.17.3.1","path":"11-tabapi-http-binding.html#tabpost-8","title":"6.17.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentities","level":"2","number":"11.18","path":"11-tabapi-http-binding.html#tabresource-temporalentities","title":"6.18\tResource: temporal/entities/"},"subsections":[{"section":{"id":"tabdescription-67","level":"3","number":"11.18.1","path":"11-tabapi-http-binding.html#tabdescription-67","title":"6.18.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-14","level":"3","number":"11.18.2","path":"11-tabapi-http-binding.html#tabresource-definition-14","title":"6.18.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-14","level":"3","number":"11.18.3","path":"11-tabapi-http-binding.html#tabresource-methods-14","title":"6.18.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-9","level":"4","number":"11.18.3.1","path":"11-tabapi-http-binding.html#tabpost-9","title":"6.18.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget-8","level":"4","number":"11.18.3.2","path":"11-tabapi-http-binding.html#tabget-8","title":"6.18.3.2\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityid","level":"2","number":"11.19","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityid","title":"6.19\tResource: temporal/entities/{entityId}"},"subsections":[{"section":{"id":"tabdescription-68","level":"3","number":"11.19.1","path":"11-tabapi-http-binding.html#tabdescription-68","title":"6.19.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-15","level":"3","number":"11.19.2","path":"11-tabapi-http-binding.html#tabresource-definition-15","title":"6.19.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-15","level":"3","number":"11.19.3","path":"11-tabapi-http-binding.html#tabresource-methods-15","title":"6.19.3\tResource methods"},"subsections":[{"section":{"id":"tabget-9","level":"4","number":"11.19.3.1","path":"11-tabapi-http-binding.html#tabget-9","title":"6.19.3.1\tGET"},"subsections":[]},{"section":{"id":"tabdelete-5","level":"4","number":"11.19.3.2","path":"11-tabapi-http-binding.html#tabdelete-5","title":"6.19.3.2\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrs","level":"2","number":"11.20","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrs","title":"6.20\tResource: temporal/entities/{entityId}/attrs/"},"subsections":[{"section":{"id":"tabdescription-69","level":"3","number":"11.20.1","path":"11-tabapi-http-binding.html#tabdescription-69","title":"6.20.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-16","level":"3","number":"11.20.2","path":"11-tabapi-http-binding.html#tabresource-definition-16","title":"6.20.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-16","level":"3","number":"11.20.3","path":"11-tabapi-http-binding.html#tabresource-methods-16","title":"6.20.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-10","level":"4","number":"11.20.3.1","path":"11-tabapi-http-binding.html#tabpost-10","title":"6.20.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid","level":"2","number":"11.21","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid","title":"6.21\tResource: temporal/entities/{entityId}/attrs/{attrId}"},"subsections":[{"section":{"id":"tabdescription-70","level":"3","number":"11.21.1","path":"11-tabapi-http-binding.html#tabdescription-70","title":"6.21.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-17","level":"3","number":"11.21.2","path":"11-tabapi-http-binding.html#tabresource-definition-17","title":"6.21.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-17","level":"3","number":"11.21.3","path":"11-tabapi-http-binding.html#tabresource-methods-17","title":"6.21.3\tResource methods"},"subsections":[{"section":{"id":"tabdelete-6","level":"4","number":"11.21.3.1","path":"11-tabapi-http-binding.html#tabdelete-6","title":"6.21.3.1\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentitiesentityidattrsattrid-instanceid","level":"2","number":"11.22","path":"11-tabapi-http-binding.html#tabresource-temporalentitiesentityidattrsattrid-instanceid","title":"6.22\tResource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId}"},"subsections":[{"section":{"id":"tabdescription-71","level":"3","number":"11.22.1","path":"11-tabapi-http-binding.html#tabdescription-71","title":"6.22.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-18","level":"3","number":"11.22.2","path":"11-tabapi-http-binding.html#tabresource-definition-18","title":"6.22.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-18","level":"3","number":"11.22.3","path":"11-tabapi-http-binding.html#tabresource-methods-18","title":"6.22.3\tResource methods"},"subsections":[{"section":{"id":"tabpatch-6","level":"4","number":"11.22.3.1","path":"11-tabapi-http-binding.html#tabpatch-6","title":"6.22.3.1\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-7","level":"4","number":"11.22.3.2","path":"11-tabapi-http-binding.html#tabdelete-7","title":"6.22.3.2\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsquery","level":"2","number":"11.23","path":"11-tabapi-http-binding.html#tabresource-entityoperationsquery","title":"6.23\tResource: entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-72","level":"3","number":"11.23.1","path":"11-tabapi-http-binding.html#tabdescription-72","title":"6.23.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-19","level":"3","number":"11.23.2","path":"11-tabapi-http-binding.html#tabresource-definition-19","title":"6.23.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-19","level":"3","number":"11.23.3","path":"11-tabapi-http-binding.html#tabresource-methods-19","title":"6.23.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-11","level":"4","number":"11.23.3.1","path":"11-tabapi-http-binding.html#tabpost-11","title":"6.23.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-temporalentityoperationsquery","level":"2","number":"11.24","path":"11-tabapi-http-binding.html#tabresource-temporalentityoperationsquery","title":"6.24\tResource: temporal/entityOperations/query"},"subsections":[{"section":{"id":"tabdescription-73","level":"3","number":"11.24.1","path":"11-tabapi-http-binding.html#tabdescription-73","title":"6.24.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-20","level":"3","number":"11.24.2","path":"11-tabapi-http-binding.html#tabresource-definition-20","title":"6.24.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-20","level":"3","number":"11.24.3","path":"11-tabapi-http-binding.html#tabresource-methods-20","title":"6.24.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-12","level":"4","number":"11.24.3.1","path":"11-tabapi-http-binding.html#tabpost-12","title":"6.24.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-types","level":"2","number":"11.25","path":"11-tabapi-http-binding.html#tabresource-types","title":"6.25\tResource: types/"},"subsections":[{"section":{"id":"tabdescription-74","level":"3","number":"11.25.1","path":"11-tabapi-http-binding.html#tabdescription-74","title":"6.25.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-21","level":"3","number":"11.25.2","path":"11-tabapi-http-binding.html#tabresource-definition-21","title":"6.25.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-21","level":"3","number":"11.25.3","path":"11-tabapi-http-binding.html#tabresource-methods-21","title":"6.25.3\tResource methods"},"subsections":[{"section":{"id":"tabget-10","level":"4","number":"11.25.3.1","path":"11-tabapi-http-binding.html#tabget-10","title":"6.25.3.1\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-typestype","level":"2","number":"11.26","path":"11-tabapi-http-binding.html#tabresource-typestype","title":"6.26\tResource: types/{type}"},"subsections":[{"section":{"id":"tabdescription-75","level":"3","number":"11.26.1","path":"11-tabapi-http-binding.html#tabdescription-75","title":"6.26.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-22","level":"3","number":"11.26.2","path":"11-tabapi-http-binding.html#tabresource-definition-22","title":"6.26.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-22","level":"3","number":"11.26.3","path":"11-tabapi-http-binding.html#tabresource-methods-22","title":"6.26.3\tResource methods"},"subsections":[{"section":{"id":"tabget-11","level":"4","number":"11.26.3.1","path":"11-tabapi-http-binding.html#tabget-11","title":"6.26.3.1\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributes","level":"2","number":"11.27","path":"11-tabapi-http-binding.html#tabresource-attributes","title":"6.27\tResource: attributes/"},"subsections":[{"section":{"id":"tabdescription-76","level":"3","number":"11.27.1","path":"11-tabapi-http-binding.html#tabdescription-76","title":"6.27.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-23","level":"3","number":"11.27.2","path":"11-tabapi-http-binding.html#tabresource-definition-23","title":"6.27.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-23","level":"3","number":"11.27.3","path":"11-tabapi-http-binding.html#tabresource-methods-23","title":"6.27.3\tResource methods"},"subsections":[{"section":{"id":"tabget-12","level":"4","number":"11.27.3.1","path":"11-tabapi-http-binding.html#tabget-12","title":"6.27.3.1\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-attributesattrid","level":"2","number":"11.28","path":"11-tabapi-http-binding.html#tabresource-attributesattrid","title":"6.28\tResource: attributes/{attrId}"},"subsections":[{"section":{"id":"tabdescription-77","level":"3","number":"11.28.1","path":"11-tabapi-http-binding.html#tabdescription-77","title":"6.28.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-24","level":"3","number":"11.28.2","path":"11-tabapi-http-binding.html#tabresource-definition-24","title":"6.28.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-24","level":"3","number":"11.28.3","path":"11-tabapi-http-binding.html#tabresource-methods-24","title":"6.28.3\tResource methods"},"subsections":[{"section":{"id":"tabget-13","level":"4","number":"11.28.3.1","path":"11-tabapi-http-binding.html#tabget-13","title":"6.28.3.1\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontexts","level":"2","number":"11.29","path":"11-tabapi-http-binding.html#tabresource-jsonldcontexts","title":"6.29\tResource: jsonldContexts/"},"subsections":[{"section":{"id":"tabdescription-78","level":"3","number":"11.29.1","path":"11-tabapi-http-binding.html#tabdescription-78","title":"6.29.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-25","level":"3","number":"11.29.2","path":"11-tabapi-http-binding.html#tabresource-definition-25","title":"6.29.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-25","level":"3","number":"11.29.3","path":"11-tabapi-http-binding.html#tabresource-methods-25","title":"6.29.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-13","level":"4","number":"11.29.3.1","path":"11-tabapi-http-binding.html#tabpost-13","title":"6.29.3.1\tPOST"},"subsections":[]},{"section":{"id":"tabget-14","level":"4","number":"11.29.3.2","path":"11-tabapi-http-binding.html#tabget-14","title":"6.29.3.2\tGET"},"subsections":[]}]}]},{"section":{"id":"tabresource-jsonldcontextscontextid","level":"2","number":"11.30","path":"11-tabapi-http-binding.html#tabresource-jsonldcontextscontextid","title":"6.30\tResource: jsonldContexts/{contextId}"},"subsections":[{"section":{"id":"tabdescription-79","level":"3","number":"11.30.1","path":"11-tabapi-http-binding.html#tabdescription-79","title":"6.30.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-26","level":"3","number":"11.30.2","path":"11-tabapi-http-binding.html#tabresource-definition-26","title":"6.30.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-26","level":"3","number":"11.30.3","path":"11-tabapi-http-binding.html#tabresource-methods-26","title":"6.30.3\tResource methods"},"subsections":[{"section":{"id":"tabget-15","level":"4","number":"11.30.3.1","path":"11-tabapi-http-binding.html#tabget-15","title":"6.30.3.1\tGET"},"subsections":[]},{"section":{"id":"tabdelete-8","level":"4","number":"11.30.3.2","path":"11-tabapi-http-binding.html#tabdelete-8","title":"6.30.3.2\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-entityoperationsmerge","level":"2","number":"11.31","path":"11-tabapi-http-binding.html#tabresource-entityoperationsmerge","title":"6.31\tResource: entityOperations/merge"},"subsections":[{"section":{"id":"tabdescription-80","level":"3","number":"11.31.1","path":"11-tabapi-http-binding.html#tabdescription-80","title":"6.31.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-27","level":"3","number":"11.31.2","path":"11-tabapi-http-binding.html#tabresource-definition-27","title":"6.31.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-27","level":"3","number":"11.31.3","path":"11-tabapi-http-binding.html#tabresource-methods-27","title":"6.31.3\tResource methods"},"subsections":[{"section":{"id":"tabpost-14","level":"4","number":"11.31.3.1","path":"11-tabapi-http-binding.html#tabpost-14","title":"6.31.3.1\tPOST"},"subsections":[]}]}]},{"section":{"id":"tabresource-entitymapsentitymapid","level":"2","number":"11.32","path":"11-tabapi-http-binding.html#tabresource-entitymapsentitymapid","title":"6.32\tResource: entityMaps/{entityMapId}"},"subsections":[{"section":{"id":"tabdescription-81","level":"3","number":"11.32.1","path":"11-tabapi-http-binding.html#tabdescription-81","title":"6.32.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-28","level":"3","number":"11.32.2","path":"11-tabapi-http-binding.html#tabresource-definition-28","title":"6.32.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-28","level":"3","number":"11.32.3","path":"11-tabapi-http-binding.html#tabresource-methods-28","title":"6.32.3\tResource methods"},"subsections":[{"section":{"id":"tabget-16","level":"4","number":"11.32.3.1","path":"11-tabapi-http-binding.html#tabget-16","title":"6.32.3.1\tGET"},"subsections":[]},{"section":{"id":"tabpatch-7","level":"4","number":"11.32.3.2","path":"11-tabapi-http-binding.html#tabpatch-7","title":"6.32.3.2\tPATCH"},"subsections":[]},{"section":{"id":"tabdelete-9","level":"4","number":"11.32.3.3","path":"11-tabapi-http-binding.html#tabdelete-9","title":"6.32.3.3\tDELETE"},"subsections":[]}]}]},{"section":{"id":"tabresource-infosourceidentity","level":"2","number":"11.33","path":"11-tabapi-http-binding.html#tabresource-infosourceidentity","title":"6.33\tResource: info/sourceIdentity"},"subsections":[{"section":{"id":"tabdescription-82","level":"3","number":"11.33.1","path":"11-tabapi-http-binding.html#tabdescription-82","title":"6.33.1\tDescription"},"subsections":[]},{"section":{"id":"tabresource-definition-29","level":"3","number":"11.33.2","path":"11-tabapi-http-binding.html#tabresource-definition-29","title":"6.33.2\tResource definition"},"subsections":[]},{"section":{"id":"tabresource-methods-29","level":"3","number":"11.33.3","path":"11-tabapi-http-binding.html#tabresource-methods-29","title":"6.33.3\tResource methods"},"subsections":[{"section":{"id":"tabget-17","level":"4","number":"11.33.3.1","path":"11-tabapi-http-binding.html#tabget-17","title":"6.33.3.1\tGET"},"subsections":[]}]}]},{"section":{"id":"resource-entitymaps","level":"2","number":"11.34","path":"11-tabapi-http-binding.html#resource-entitymaps","title":"6.34 Resource: entityMaps"},"subsections":[{"section":{"id":"description-3","level":"3","number":"11.34.1","path":"11-tabapi-http-binding.html#description-3","title":"6.34.1 Description"},"subsections":[]},{"section":{"id":"resource-definition","level":"3","number":"11.34.2","path":"11-tabapi-http-binding.html#resource-definition","title":"6.34.2 Resource definition"},"subsections":[]},{"section":{"id":"resource-methods","level":"3","number":"11.34.3","path":"11-tabapi-http-binding.html#resource-methods","title":"6.34.3 Resource methods"},"subsections":[{"section":{"id":"post","level":"4","number":"11.34.3.1","path":"11-tabapi-http-binding.html#post","title":"6.34.3.2 POST"},"subsections":[]}]}]},{"section":{"id":"resource-temporalentitymaps","level":"2","number":"11.35","path":"11-tabapi-http-binding.html#resource-temporalentitymaps","title":"6.35 Resource: temporal/entityMaps"},"subsections":[{"section":{"id":"description-4","level":"3","number":"11.35.1","path":"11-tabapi-http-binding.html#description-4","title":"6.35.1 Description"},"subsections":[]},{"section":{"id":"resource-definition-1","level":"3","number":"11.35.2","path":"11-tabapi-http-binding.html#resource-definition-1","title":"6.35.2 Resource definition"},"subsections":[]},{"section":{"id":"resource-methods-1","level":"3","number":"11.35.3","path":"11-tabapi-http-binding.html#resource-methods-1","title":"6.35.3 Resource methods"},"subsections":[{"section":{"id":"get","level":"4","number":"11.35.3.1","path":"11-tabapi-http-binding.html#get","title":"6.35.3.1 GET"},"subsections":[]},{"section":{"id":"post-1","level":"4","number":"11.35.3.2","path":"11-tabapi-http-binding.html#post-1","title":"6.35.3.2 POST"},"subsections":[]}]}]}]},{"section":{"id":"tabapi-mqtt-notification-binding","level":"1","number":"12","path":"12-tabapi-mqtt-notification-binding.html#tabapi-mqtt-notification-binding","title":"7\tAPI MQTT Notification Binding"},"subsections":[{"section":{"id":"tabintroduction-22","level":"2","number":"12.1","path":"12-tabapi-mqtt-notification-binding.html#tabintroduction-22","title":"7.1\tIntroduction"},"subsections":[]},{"section":{"id":"tabnotification-behaviour-3","level":"2","number":"12.2","path":"12-tabapi-mqtt-notification-binding.html#tabnotification-behaviour-3","title":"7.2\tNotification behaviour"},"subsections":[]}]},{"section":{"id":"annex-a-normative-ngsi-ld-identifier-considerations","level":"1","number":"13","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#annex-a-normative-ngsi-ld-identifier-considerations","title":"Annex A (normative): NGSI-LD identifier considerations"},"subsections":[{"section":{"id":"a.1tabintroduction","level":"2","number":"13.1","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.1tabintroduction","title":"A.1\tIntroduction"},"subsections":[]},{"section":{"id":"a.2tabentity-identifiers","level":"2","number":"13.2","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.2tabentity-identifiers","title":"A.2\tEntity identifiers"},"subsections":[]},{"section":{"id":"a.3tabngsi-ld-namespace","level":"2","number":"13.3","path":"13-annex-a-normative-ngsi-ld-identifier-considerations.html#a.3tabngsi-ld-namespace","title":"A.3\tNGSI-LD namespace"},"subsections":[]}]},{"section":{"id":"annex-b-normative-core-ngsi-ld-context-definition","level":"1","number":"14","path":"14-annex-b-normative-core-ngsi-ld-context-definition.html#annex-b-normative-core-ngsi-ld-context-definition","title":"Annex B (normative): Core NGSI-LD @context definition"},"subsections":[]},{"section":{"id":"annex-c-informative-examples-of-using-the-api","level":"1","number":"15","path":"15-annex-c-informative-examples-of-using-the-api.html#annex-c-informative-examples-of-using-the-api","title":"Annex C (informative): Examples of using the API"},"subsections":[{"section":{"id":"c.1tabintroduction","level":"2","number":"15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.1tabintroduction","title":"C.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.2tabentity-representation","level":"2","number":"15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2tabentity-representation","title":"C.2\tEntity Representation"},"subsections":[{"section":{"id":"c.2.1tabproperty-graph","level":"3","number":"15.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.1tabproperty-graph","title":"C.2.1\tProperty Graph"},"subsections":[]},{"section":{"id":"c.2.2tabvehicle-entity","level":"3","number":"15.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.2tabvehicle-entity","title":"C.2.2\tVehicle Entity"},"subsections":[]},{"section":{"id":"c.2.3tabparking-entity","level":"3","number":"15.2.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.3tabparking-entity","title":"C.2.3\tParking Entity"},"subsections":[]},{"section":{"id":"c.2.4tabcontext","level":"3","number":"15.2.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.2.4tabcontext","title":"C.2.4\t@context"},"subsections":[]}]},{"section":{"id":"c.3tabcontext-source-registration","level":"2","number":"15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.3tabcontext-source-registration","title":"C.3\tContext Source Registration"},"subsections":[]},{"section":{"id":"c.4tabcontext-subscription","level":"2","number":"15.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.4tabcontext-subscription","title":"C.4\tContext Subscription"},"subsections":[]},{"section":{"id":"c.5tabhttp-rest-api-examples","level":"2","number":"15.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5tabhttp-rest-api-examples","title":"C.5\tHTTP REST API Examples"},"subsections":[{"section":{"id":"c.5.1tabintroduction","level":"3","number":"15.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.1tabintroduction","title":"C.5.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.2tabcreate-entity-of-type-vehicle","level":"3","number":"15.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2tabcreate-entity-of-type-vehicle","title":"C.5.2\tCreate Entity of Type Vehicle"},"subsections":[{"section":{"id":"c.5.2.1tabhttp-request","level":"4","number":"15.5.2.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.1tabhttp-request","title":"C.5.2.1\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.2.2tabhttp-response","level":"4","number":"15.5.2.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.2.2tabhttp-response","title":"C.5.2.2\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.3tabquery-entities","level":"3","number":"15.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3tabquery-entities","title":"C.5.3\tQuery Entities"},"subsections":[{"section":{"id":"c.5.3.1tabintroduction","level":"4","number":"15.5.3.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.1tabintroduction","title":"C.5.3.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.3.2tabhttp-request","level":"4","number":"15.5.3.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.2tabhttp-request","title":"C.5.3.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.3.3tabhttp-response","level":"4","number":"15.5.3.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.3.3tabhttp-response","title":"C.5.3.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.4tabquery-entities-pagination","level":"3","number":"15.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4tabquery-entities-pagination","title":"C.5.4\tQuery Entities (Pagination)"},"subsections":[{"section":{"id":"c.5.4.1tabintroduction","level":"4","number":"15.5.4.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.1tabintroduction","title":"C.5.4.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.4.2tabhttp-request","level":"4","number":"15.5.4.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.2tabhttp-request","title":"C.5.4.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.4.3tabhttp-response","level":"4","number":"15.5.4.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.4.3tabhttp-response","title":"C.5.4.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.5tabtemporal-query","level":"3","number":"15.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5tabtemporal-query","title":"C.5.5\tTemporal Query"},"subsections":[{"section":{"id":"c.5.5.1tabintroduction","level":"4","number":"15.5.5.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.1tabintroduction","title":"C.5.5.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.5.2tabhttp-request-1","level":"4","number":"15.5.5.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.2tabhttp-request-1","title":"C.5.5.2\tHTTP Request #1"},"subsections":[]},{"section":{"id":"c.5.5.3tabhttp-response-1","level":"4","number":"15.5.5.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.3tabhttp-response-1","title":"C.5.5.3\tHTTP Response #1"},"subsections":[]},{"section":{"id":"c.5.5.3tabhttp-request-2","level":"4","number":"15.5.5.4","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.3tabhttp-request-2","title":"C.5.5.3\tHTTP Request #2"},"subsections":[]},{"section":{"id":"c.5.5.4tabhttp-response-2","level":"4","number":"15.5.5.5","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.5.4tabhttp-response-2","title":"C.5.5.4\tHTTP Response #2"},"subsections":[]}]},{"section":{"id":"c.5.6tabtemporal-query-simplified-representation","level":"3","number":"15.5.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6tabtemporal-query-simplified-representation","title":"C.5.6\tTemporal Query (Simplified Representation)"},"subsections":[{"section":{"id":"c.5.6.1tabintroduction","level":"4","number":"15.5.6.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.1tabintroduction","title":"C.5.6.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.6.2tabhttp-request","level":"4","number":"15.5.6.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.2tabhttp-request","title":"C.5.6.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.6.3tabhttp-response","level":"4","number":"15.5.6.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.6.3tabhttp-response","title":"C.5.6.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.7tabretrieve-available-entity-types","level":"3","number":"15.5.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7tabretrieve-available-entity-types","title":"C.5.7\tRetrieve Available Entity Types"},"subsections":[{"section":{"id":"c.5.7.1tabintroduction","level":"4","number":"15.5.7.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.1tabintroduction","title":"C.5.7.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.7.2tabhttp-request","level":"4","number":"15.5.7.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.2tabhttp-request","title":"C.5.7.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.7.3tabhttp-response","level":"4","number":"15.5.7.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.7.3tabhttp-response","title":"C.5.7.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.8tabretrieve-details-of-available-entity-types","level":"3","number":"15.5.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8tabretrieve-details-of-available-entity-types","title":"C.5.8\tRetrieve Details of Available Entity Types"},"subsections":[{"section":{"id":"c.5.8.1tabintroduction","level":"4","number":"15.5.8.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.1tabintroduction","title":"C.5.8.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.8.2tabhttp-request","level":"4","number":"15.5.8.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.2tabhttp-request","title":"C.5.8.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.8.3tabhttp-response","level":"4","number":"15.5.8.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.8.3tabhttp-response","title":"C.5.8.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.9tabretrieve-available-entity-type-information","level":"3","number":"15.5.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9tabretrieve-available-entity-type-information","title":"C.5.9\tRetrieve Available Entity Type Information"},"subsections":[{"section":{"id":"c.5.9.1tabintroduction","level":"4","number":"15.5.9.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.1tabintroduction","title":"C.5.9.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.9.2tabhttp-request","level":"4","number":"15.5.9.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.2tabhttp-request","title":"C.5.9.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.9.3tabhttp-response","level":"4","number":"15.5.9.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.9.3tabhttp-response","title":"C.5.9.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.10tabretrieve-available-attributes","level":"3","number":"15.5.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10tabretrieve-available-attributes","title":"C.5.10\tRetrieve Available Attributes"},"subsections":[{"section":{"id":"c.5.10.1tabintroduction","level":"4","number":"15.5.10.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.1tabintroduction","title":"C.5.10.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.10.2tabhttp-request","level":"4","number":"15.5.10.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.2tabhttp-request","title":"C.5.10.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.10.3tabhttp-response","level":"4","number":"15.5.10.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.10.3tabhttp-response","title":"C.5.10.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.11tabretrieve-details-of-available-attributes","level":"3","number":"15.5.11","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11tabretrieve-details-of-available-attributes","title":"C.5.11\tRetrieve Details of Available Attributes"},"subsections":[{"section":{"id":"c.5.11.1tabintroduction","level":"4","number":"15.5.11.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.1tabintroduction","title":"C.5.11.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.11.2tabhttp-request","level":"4","number":"15.5.11.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.2tabhttp-request","title":"C.5.11.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.11.3tabhttp-response","level":"4","number":"15.5.11.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.11.3tabhttp-response","title":"C.5.11.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.12tabretrieve-available-attribute-information","level":"3","number":"15.5.12","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12tabretrieve-available-attribute-information","title":"C.5.12\tRetrieve Available Attribute Information"},"subsections":[{"section":{"id":"c.5.12.1tabintroduction","level":"4","number":"15.5.12.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.1tabintroduction","title":"C.5.12.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.12.2tabhttp-request","level":"4","number":"15.5.12.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.2tabhttp-request","title":"C.5.12.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.12.3tabhttp-response","level":"4","number":"15.5.12.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.12.3tabhttp-response","title":"C.5.12.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.13tabquery-entities-natural-language-filtering","level":"3","number":"15.5.13","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13tabquery-entities-natural-language-filtering","title":"C.5.13\tQuery Entities (Natural Language Filtering)"},"subsections":[{"section":{"id":"c.5.13.1tabintroduction","level":"4","number":"15.5.13.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.1tabintroduction","title":"C.5.13.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.13.2tabhttp-request","level":"4","number":"15.5.13.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.2tabhttp-request","title":"C.5.13.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.13.3tabhttp-response","level":"4","number":"15.5.13.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.13.3tabhttp-response","title":"C.5.13.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.14tabtemporal-query-aggregated-representation","level":"3","number":"15.5.14","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14tabtemporal-query-aggregated-representation","title":"C.5.14\tTemporal Query (Aggregated Representation)"},"subsections":[{"section":{"id":"c.5.14.1tabintroduction","level":"4","number":"15.5.14.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.1tabintroduction","title":"C.5.14.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.14.2tabhttp-request","level":"4","number":"15.5.14.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.2tabhttp-request","title":"C.5.14.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.14.3tabhttp-response","level":"4","number":"15.5.14.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.14.3tabhttp-response","title":"C.5.14.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.15tabscope-queries","level":"3","number":"15.5.15","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15tabscope-queries","title":"C.5.15\tScope Queries"},"subsections":[{"section":{"id":"c.5.15.1tabintroduction","level":"4","number":"15.5.15.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.1tabintroduction","title":"C.5.15.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.15.2tabhttp-request","level":"4","number":"15.5.15.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.2tabhttp-request","title":"C.5.15.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.15.3tabhttp-response","level":"4","number":"15.5.15.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.15.3tabhttp-response","title":"C.5.15.3\tHTTP Response"},"subsections":[]}]},{"section":{"id":"c.5.16tabtemporal-scope-queries","level":"3","number":"15.5.16","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16tabtemporal-scope-queries","title":"C.5.16\tTemporal Scope Queries"},"subsections":[{"section":{"id":"c.5.16.1tabintroduction","level":"4","number":"15.5.16.1","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.1tabintroduction","title":"C.5.16.1\tIntroduction"},"subsections":[]},{"section":{"id":"c.5.16.2tabhttp-request","level":"4","number":"15.5.16.2","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.2tabhttp-request","title":"C.5.16.2\tHTTP Request"},"subsections":[]},{"section":{"id":"c.5.16.3tabhttp-response","level":"4","number":"15.5.16.3","path":"15-annex-c-informative-examples-of-using-the-api.html#c.5.16.3tabhttp-response","title":"C.5.16.3\tHTTP Response"},"subsections":[]}]}]},{"section":{"id":"c.6tabdate-representation","level":"2","number":"15.6","path":"15-annex-c-informative-examples-of-using-the-api.html#c.6tabdate-representation","title":"C.6\tDate Representation"},"subsections":[]},{"section":{"id":"c.7tabcontext-utilization-clarifications","level":"2","number":"15.7","path":"15-annex-c-informative-examples-of-using-the-api.html#c.7tabcontext-utilization-clarifications","title":"C.7\t@context utilization clarifications"},"subsections":[]},{"section":{"id":"c.8tablink-header-utilization-clarifications","level":"2","number":"15.8","path":"15-annex-c-informative-examples-of-using-the-api.html#c.8tablink-header-utilization-clarifications","title":"C.8\tLink header utilization clarifications"},"subsections":[]},{"section":{"id":"c.9tabcontext-processing-clarifications","level":"2","number":"15.9","path":"15-annex-c-informative-examples-of-using-the-api.html#c.9tabcontext-processing-clarifications","title":"C.9\t@context processing clarifications"},"subsections":[]},{"section":{"id":"c.10-valuetype-datatype-utilization-clarifications","level":"2","number":"15.10","path":"15-annex-c-informative-examples-of-using-the-api.html#c.10-valuetype-datatype-utilization-clarifications","title":"C.10 ValueType datatype utilization clarifications"},"subsections":[]}]},{"section":{"id":"annex-d-informative-transformation-algorithms","level":"1","number":"16","path":"16-annex-d-informative-transformation-algorithms.html#annex-d-informative-transformation-algorithms","title":"Annex D (informative): Transformation Algorithms"},"subsections":[{"section":{"id":"d.1tabintroduction","level":"2","number":"16.1","path":"16-annex-d-informative-transformation-algorithms.html#d.1tabintroduction","title":"D.1\tIntroduction"},"subsections":[]},{"section":{"id":"d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","level":"2","number":"16.2","path":"16-annex-d-informative-transformation-algorithms.html#d.2tabalgorithm-for-transforming-an-ngsi-ld-entity-into-a-json-ld-document-alg1","title":"D.2\tAlgorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)"},"subsections":[]},{"section":{"id":"d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","level":"2","number":"16.3","path":"16-annex-d-informative-transformation-algorithms.html#d.3tabalgorithm-for-transforming-an-ngsi-ld-property-into-json-ld-alg1.1","title":"D.3\tAlgorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1)"},"subsections":[]},{"section":{"id":"d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","level":"2","number":"16.4","path":"16-annex-d-informative-transformation-algorithms.html#d.4tabalgorithm-for-transforming-an-ngsi-ld-relationship-into-json-ld-alg1.2","title":"D.4\tAlgorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2)"},"subsections":[]}]},{"section":{"id":"annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","level":"1","number":"17","path":"17-annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model.html#annex-e-informative-rdf-compatible-specification-of-ngsi-ld-meta-model","title":"Annex E (informative): RDF-compatible specification of NGSI-LD meta-model"},"subsections":[]},{"section":{"id":"annex-f-informative-conventions-and-syntax-guidelines","level":"1","number":"18","path":"18-annex-f-informative-conventions-and-syntax-guidelines.html#annex-f-informative-conventions-and-syntax-guidelines","title":"Annex F (informative): Conventions and syntax guidelines"},"subsections":[]},{"section":{"id":"annex-g-informative-localization-and-internationalization-support","level":"1","number":"19","path":"19-annex-g-informative-localization-and-internationalization-support.html#annex-g-informative-localization-and-internationalization-support","title":"Annex G (informative): Localization and Internationalization Support"},"subsections":[{"section":{"id":"g.0tabforeword","level":"2","number":"19.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.0tabforeword","title":"G.0\tForeword"},"subsections":[]},{"section":{"id":"g.1tabintroduction","level":"2","number":"19.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1tabintroduction","title":"G.1\tIntroduction"},"subsections":[{"section":{"id":"g.1.0tabforeword","level":"3","number":"19.2.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.0tabforeword","title":"G.1.0\tForeword"},"subsections":[]},{"section":{"id":"g.1.1tabassociating-an-entity-with-a-natural-language","level":"3","number":"19.2.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.1tabassociating-an-entity-with-a-natural-language","title":"G.1.1\tAssociating an Entity with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.2tabassociating-a-property-with-a-natural-language","level":"3","number":"19.2.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.2tabassociating-a-property-with-a-natural-language","title":"G.1.2\tAssociating a Property with a Natural Language"},"subsections":[]},{"section":{"id":"g.1.3tabassociating-as-equivalent-entity","level":"3","number":"19.2.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.1.3tabassociating-as-equivalent-entity","title":"G.1.3\tAssociating as equivalent entity"},"subsections":[]}]},{"section":{"id":"g.2tabnatural-language-collation-support","level":"2","number":"19.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2tabnatural-language-collation-support","title":"G.2\tNatural Language Collation Support"},"subsections":[{"section":{"id":"g.2.0tabforeword","level":"3","number":"19.3.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.0tabforeword","title":"G.2.0\tForeword"},"subsections":[]},{"section":{"id":"g.2.1tabmaintain-collations-as-metadata","level":"3","number":"19.3.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.1tabmaintain-collations-as-metadata","title":"G.2.1\tMaintain collations as metadata"},"subsections":[]},{"section":{"id":"g.2.2tabroute-language-sensitive-queries-via-a-proxy","level":"3","number":"19.3.3","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.2.2tabroute-language-sensitive-queries-via-a-proxy","title":"G.2.2\tRoute language sensitive queries via a proxy"},"subsections":[]}]},{"section":{"id":"g.3tablocalization-of-dates-currency-formats-etc.","level":"2","number":"19.4","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3tablocalization-of-dates-currency-formats-etc.","title":"G.3\tLocalization of Dates, Currency formats, etc."},"subsections":[{"section":{"id":"g.3.0tabforeword","level":"3","number":"19.4.1","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.0tabforeword","title":"G.3.0\tForeword"},"subsections":[]},{"section":{"id":"g.3.1tablocalizing-dates","level":"3","number":"19.4.2","path":"19-annex-g-informative-localization-and-internationalization-support.html#g.3.1tablocalizing-dates","title":"G.3.1\tLocalizing Dates"},"subsections":[]}]}]},{"section":{"id":"annex-h-informative-suggested-actuation-workflows","level":"1","number":"20","path":"20-annex-h-informative-suggested-actuation-workflows.html#annex-h-informative-suggested-actuation-workflows","title":"Annex H (informative): Suggested actuation workflows"},"subsections":[{"section":{"id":"h.1tabactuators-and-feedback-to-the-consumer","level":"2","number":"20.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.1tabactuators-and-feedback-to-the-consumer","title":"H.1\tActuators and feedback to the consumer"},"subsections":[]},{"section":{"id":"h.2tabarchitecture-for-actuation","level":"2","number":"20.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.2tabarchitecture-for-actuation","title":"H.2\tArchitecture for actuation"},"subsections":[]},{"section":{"id":"h.3tabstructure-of-commands-and-additional-properties","level":"2","number":"20.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3tabstructure-of-commands-and-additional-properties","title":"H.3\tStructure of Commands and additional Properties"},"subsections":[{"section":{"id":"h.3.0tabintroduction","level":"3","number":"20.3.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.0tabintroduction","title":"H.3.0\tIntroduction"},"subsections":[]},{"section":{"id":"h.3.1tabproperty-for-listing-available-commands","level":"3","number":"20.3.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.1tabproperty-for-listing-available-commands","title":"H.3.1\tProperty for listing available commands"},"subsections":[]},{"section":{"id":"h.3.2tabproperties-for-command-endpoints","level":"3","number":"20.3.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.3.2tabproperties-for-command-endpoints","title":"H.3.2\tProperties for command endpoints"},"subsections":[]}]},{"section":{"id":"h.4tabcommunication-model","level":"2","number":"20.4","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4tabcommunication-model","title":"H.4\tCommunication model"},"subsections":[{"section":{"id":"h.4.1tabpossible-communication-models","level":"3","number":"20.4.1","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.1tabpossible-communication-models","title":"H.4.1\tPossible communication models"},"subsections":[]},{"section":{"id":"h.4.2tabsubscriptionnotification-model","level":"3","number":"20.4.2","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.2tabsubscriptionnotification-model","title":"H.4.2\tSubscription/notification model"},"subsections":[]},{"section":{"id":"h.4.3tabforwarding-model","level":"3","number":"20.4.3","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.4.3tabforwarding-model","title":"H.4.3\tForwarding model"},"subsections":[]}]},{"section":{"id":"h.5tabimplementation-of-the-subscription-based-actuation-workflow","level":"2","number":"20.5","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.5tabimplementation-of-the-subscription-based-actuation-workflow","title":"H.5\tImplementation of the subscription-based actuation workflow"},"subsections":[]},{"section":{"id":"h.6tabimplementation-of-the-registration-based-actuation-workflow","level":"2","number":"20.6","path":"20-annex-h-informative-suggested-actuation-workflows.html#h.6tabimplementation-of-the-registration-based-actuation-workflow","title":"H.6\tImplementation of the registration-based actuation workflow"},"subsections":[]}]},{"section":{"id":"annex-i-informative-change-history","level":"1","number":"21","path":"21-annex-i-informative-change-history.html#annex-i-informative-change-history","title":"Annex I (informative): Change history"},"subsections":[]},{"section":{"id":"history","level":"1","number":"22","path":"22-history.html#history","title":"History"},"subsections":[]}]} \ No newline at end of file diff --git a/public/styling.css b/public/styling.css index 44c16907f78c65d0eb6f65bb89bf706ea24af5d9..a1e2cf47dc43ff1ba0a92bd12a121b98a0fb5f71 100644 --- a/public/styling.css +++ b/public/styling.css @@ -26,6 +26,7 @@ body { height: 100%; width: unset; position: relative; + background-color: rgba(100, 100, 100, 0.6); overflow-y: auto; scrollbar-width: none; @@ -518,7 +519,10 @@ body { /* margin: auto; */ /* max-width: 920px; min-width: 360px; */ + max-width: 75%; + left: 275px; position: relative; + padding: 2rem; word-wrap: break-word; } @@ -996,3 +1000,46 @@ code > span.in { .TAN > div:first-child { text-wrap: nowrap; } + +#Table_6\.2-1 + table tbody { + tr { + background-color: #fff !important; + } + + tr:nth-child(4), + tr:nth-child(5), + tr:nth-child(6), + tr:nth-child(7), + tr:nth-child(10), + tr:nth-child(11), + tr:nth-child(12), + tr:nth-child(15), + tr:nth-child(16), + tr:nth-child(17), + tr:nth-child(19), + tr:nth-child(21), + tr:nth-child(24), + tr:nth-child(25), + tr:nth-child(26), + tr:nth-child(29), + tr:nth-child(30), + tr:nth-child(31), + tr:nth-child(33), + tr:nth-child(35), + tr:nth-child(37), + tr:nth-child(40), + tr:nth-child(41), + tr:nth-child(43), + tr:nth-child(46), + tr:nth-child(47), + tr:nth-child(49), + tr:nth-child(50), + tr:nth-child(53), + tr:nth-child(54), + tr:nth-child(58), + tr:nth-child(61), + tr:nth-child(62), + tr:nth-child(63) { + background-color: #f8f8f8 !important; + } +}